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Note 



Certain sections of the following reference manual are written 
in a primer-like style, especially parts of the introduction and the dis- 
cussion of macros. However, it is assumed that the reader is familiar 
with the logical operation of general-purpose digital computers, and, in 
particular, is acquainted with the SDS 940 instruction set (see the SDS 
publication, SDS 940 Computer Reference Manual , No. 90 06 40A, 
August, 1966. 

The preface contains a discussion of the differences between 
NARP and ARPAS. 

Acknowledgment 

Much of this manual is similar to the ARPAS manual ( ARPAS , 
Reference Manual for Time-Sharing Assembler for the SDS 930 , Document 
R-26, February 24, 1967), written by Wayne Lichtenberger, and some 
paragraphs are taken verbatim from the ARPAS manual. 

This manual was developed by the University of California at 
Berkeley under contract to Advanced Research Projects Agency and 
modified by Tymshare to reflect certain additions to the assembler. 
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0.0 Differences Between NARP and ArPAS 



NARP (new ARPA S) has supplemented ARPAS as the assembler for 
assembly language programs written for Tymshare's XDS 940. The 
execution speed of NARP is considerably greater than that of ARPAS, and 
that is the main reason for the changeover. All users are encouraged to 
change their programs over to the NARP language as soon as practicable 
and new program^ should surely be written in NARP. DDT and FOS will 
load programs assembled in either language or both. 

NARP is by and large a superset of ARPAS, but there are some 
notable exceptions, the majority of which are described below. 

The following list of differences between NARP and ARPAS is 
ordered after the ARPAS manual, with a few exceptions. To avoid am- 
biguities, a blank character is often denoted by a *_^' . 

« 

1) NARP is a one-pass assembler, not a two-pass assembler 
like ARPAS. Thus any sections of programs which depend 
on the fact that ARPAS is two passes will in all proba- 
bility have to be carefully rewritten before NARP can 
handle it. 

2) In addition to the opcodes listed in the ARPAS manual. 
Appendix A, NARP handles many additional opcodes. See 
NARP manual. Appendix A. 

• 3) A sjnnbol in NARP is a string of letters and digits that 
is not a number. A number is any one of the following: 

a) a string of digits 

b) a string of digits followed by the letter 'D* 

c) a string of digits followed by the letter 'B' 

d) a string of digits followed by the letter 'B' 
followed by a single digit. Thus, 14D2 and 14B10 
are symbols, whereas 777B9 is a number. 
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4) The seven characters ! # Z & ® \ t are recognized by NARP. 
Thus they may be used freely, usually in strings, but not 
always, since some of them have meaning in NARP, Except 
for 135B (multiple blank) and 155B (carriage return), all 
characters with a value greater than 77B are ignored by 
NARP. 

5) The classification of opcodes has been completely revised 
in NARP: 

class 0: the opcode may or may not have an operand 

(e.g., NOP) 
class 1: the opcode has no operand (e.g., CLA) 
class 2: the opcode has an operand (e.g., ADD) 

In addition to its class, a given operand is either a 
shift instruction or a non-shift instruction (note: this 
has nothing to do with whether the action of the instruc- 
tion involves shifting, but is simply a way of distinguish- 
ing between two types of instructions). For a non-shift 

ol4 
instruction, the operand is computed mod 2 and merged 

into the instruction. For a shift instruction the follow- 
ing happens: 

a) if the indirect bit is set by '*' or '•^' then the 
value of the opcode is trimmed so that blO-b23 are 
zero and the instruction is treated as if it were 
a non-shift instruction. 

b) if the indirect bit is not set as above then the oper- 
and is computed mod 2 and merged into the instruction; 
in this case, the operand must be defined and absolute, 
(note: With reference to NARP, the statement that a 
symbol is defined means it is defined at that instant 
and not at some later point in the program.) 

See the description of OPD (22 below) for more comments on 
opcodes. 
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6) A number may appear in the opcode field. In such a case, 
the value of this number is placed in b0-b8 of the in- 
struction. The opcode has class (i.e., operand optional). 

7) NARP does not keep track of null symbols. 

8) The tag field of an instruction must be defined (in the 
NARP sense, see 5b above) and absolute. 

9) In ARPAS an expression may have a relocation factor of 
either (absolute) or 1 (relocatable). In NARP, however, 
an expression may have any relocation factor, including a 
negative one. 

10) The ARPAS notation (<letter string>) for operators does 
not exist in NARP: 

ARPAS NARP 



(NOT) 


S 




(R) 


does 


not exist, see 16 below 


(LSS) 


< 




(GRT) 


> 




(EQU) 


« 




(AND) 


& 




(OR) 


1 

• 




(EOR) 


7. 





11) The precedence of operators is different in NARP than it 

is in ARPAS (see 17 below). In most cases this makes little 
difference and need only be worried about for things like 
(AND) (maybe not even in this case, since the description 
in the ARPAS manual may not correspond with reality) . 

12) A NARP expression may contain an expression enclosed in 
square brackets as a primary. For example, A EQU [N-3]*8 
is legal. 
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13) A NARP expression may contain any number of relational 
operators. .,. 

14) String constants are right-justified . Thus 'A* « * , , ,A * « 
•j^A' - \A* , 'Aj^' - 'aa.Aa.' ^ 'aV' Also, a string con- 
stant may be at most four characters long; if it is longer, 
then an error message is typed and the first four charac- 
ters of the string are taken as the value. 

15) A NARP expression has the following BNF description: 

<primary> :: - <symbol>|<constant>|[<expression>] 

<basic expression> :: = <primary>|<primary> <binary operator> 

<basic express ion> 

<expression> :: « <basic expression>|<unary operator> 

<bas ic • expr es s ion> . 

The main point in the above syntax is that two operators 
may never be adjacent, so A & (e>B is illegal (write it as 
dB 6c A) . 

16) NARP is less finicky than ARPAS about relocation factors. 
Thus a relocatable quantity can be multiplied by an absolute 
quantity, yielding a relocation factor other than or 1, 
e.g., (R) ALPHA when used to produce a string pointer becomes 
simply 3* ALPHA, The unary operator (R) does not exist in 
NARP (likewise, the directive RAD does not exist inJIARP). 
The following table shows the permissible relocation factors 
for the operands of the various operators , as well as the 
relocation factor of the result (see 17 below for descrip- 
tions of all the operators) . 

NOTE: In the following table, Rl is a symbol with relocation factor 
of 1 and R2 is a symbol with relocation factor of 2. Relocation 
factor is shortened to "rf actor". 
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operator 


relocation factor (s) 
of operand (s) 


relocation factor 
of result 


example 


t 


* 

all operands absolute 


absolute 


2t4=16, 
Rltl (error) 


* 


at least one rfactor 
must be absolute, the 
other is arbitrary 


found by multi- 
plying the value 
of the absolute 
operand times the 
rfactor of the 
other operand 


3*R2 has 
rfactor of 6 
R1*R1 (error) 


/ 


all operands absolute 


absolute 


4/2-2, 
Rl/1 (error) 


+ - 
(unary and 
binary) 


arbitrary rfactors 


found by applying 
operator to the 
relocation factors 
of the operands 


R1+R2 has 
relocation 
factor of 3 


# >- > 


arbitrary relocation 
factors, but must be 
equal 


absolute , 


Rl-Rl is 

true 

R2>R1 (error) 


& 1 


all operands absolute 


absolute 


7&3»3, 
dRl (error) 



17) The table below lists all the operators that may be used in 
NARP expressions, along with their precedence (the higher 
the precedence, the tighter the operator binds its operands) 
and some comments. 
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Operator Precedence Comment 



+ (u: 
- (u; 



t 6 exponentiation; exponent must be > 

* 5 multiplication " 
I 5 integer division 

' i) 4 unary plus (effectively a nop) 

4 negation 

4 addition 

4 subtraction 

< 3 less than 

<> 3 less than or equal to 

« 3 . equal to 

# 3 not equal to 

>- 3 greater than or equal to 

> 3 greater than 

A 2 logical not 

& 1 logical and 

I logical or 

X logical exclusive or 

18) At the^ moment, the following ARPAS opcodes are undefined 
in NARP (there is more on these opcodes in subsequent 
pages): ORG, RAD, ENTRY 

19) tEXT, ASC: The ARPAS option of specifying the length of 
the string instead of enclosing it in quotes is not allowed, 
However, the string delimiting character is not restricted 
to a quote, but may be any printing character except blank 
or semicolon. Thus TEXT %QUOTE MARK: '% is legal. Of 
course, the first character encountered is taken as the 
delimiting character. Within a string, blanks, commas, and 
semicolons have no special meaning; they are treated just 
like the other characters in the string, 

20) EQU: The expression must be defined (the ARPAS manual also 
says this is necessary, but in many cases it isn't because 
ARPAS has two passes). The relocation factor of the expres- 
sion must be in the range [-15,15]. 
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21) EXT: In the option <S)mibol> EXT, the sjnnbol must be defined 
(again this is what the ARPAS manual says, but the two-pass 
nature of ARPAS makes it possible to ignore this). In the 
option <symbol> EXT <expression>, it is not necessary that 
the symbol be defined, but the expression must be defined 
(its relocation factor is arbitrary) . At present ENTRY is 
not implemented. See 40 below for a detailed discussion of 
symbol definitions, both external and otherwise. 

22) OPD, POPD: Because of the different opcode classification 
scheme in NARP, the format of an OPD is rather different 
than in ARPAS: 

syntax: <symbol> OPD <value>[ ,<op sit>[ ,<shiftk>] ] 

semantics: 

<symb©l> - becomes defined as an opcode; if the symbol is 

already an opcode than *W* is typed as a warning 
and the previous definition is overwritten. 

Note : All of the following may be arbitrary expressions, but they 
must be defined and absolute. If an optional expression does not 
appear then the value is assumed. 

24 
<value> - computed mod 2 and used as the value for the 

opcode (see important note below) . 

<op sit> - operand situation: must have a value of 0,1, or 

2, with the following meanings: 

- operand optional 

1 - no operand 

2 - operand required 

<shif tk> - shift kludge; must have a value of or 1 
with the following meanings: 

- non- shift instruction 

1 - shift instruction 
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Note ; Although an opcode that takes operands can be defined with 
bits bl0-b23 set, the user must be careful of what he is doing. 
In particular, if such an opcode appears in an instruction which 
contains a literal or an undefined value then bits blO-b23 of the 
opcode will be set to zero. 

Warning : The usual ARPAS opcode definition of <value>,l,l will 
result in a NARP opcode which takes no operands. Thus such an 
ARPAS program will cause no error messages when assembled by NARP, 
but it will surely not run when loaded. 

23) ORG: This does not exist in NARP. There is no reasonable 
way in which a one-pass assembler (that doesn't assemble 
directly into core) can handle ORG. 

24) RAD: This does not exist in NARP because of the freer 
relocation rules that do away with (R) . 

25) IDENT: Only the first six characters of the preceding 
sjnmbol and the word * IDENT* are printed, 

26) The concatenation symbol ' . ' used in ARPAS is replaced by 
'.&' in NARP. This makes it possible to use the character 
*.* in macro definitions, in particular within strings 

(of course *.&' within a string will get removed). The 
ordinary use of '.6e* is to separate a reference to a pre- 
ceding alphanumeric character. In all other cases ' .&' 
is superfluous, although legal. During a macro definition, 
* .&' is detected at all levels ("level" here refers to the 
nesting of MACRO - ENDM pairs) , but is only removed at the 
top level. Thus the following will work fine, even if D(I) 
is the null string: 



A 


MACRO 


D 


B 


MACRO 


E 




TEXT 


'ABC.&D(I)E(J)' 




ENDM 






ENDM 
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27) Whole-line comments (i.e., lines of text beginning with an 
asterisk) are not saved as part of a macro definition, but 
comments following instructions are. Thus it behooves the 
programmer to use these comments sparingly as they only 
gobble up core space. 

28) A dupnny subscript may not have value -1. Instead of follow- 
ing a macro call with an asterisk to set the indirect bit 

on some argument, the ' ♦-* convention should be used. An 
asterisk following a macro call or a directive is an error. 

29) The conventions concerning a dummy subscript of value zero 
are somewhat different. First of all, D(0) and D(l-l) are 
completely equivalent as far as NARP is concerned (only the 
subscript value, not its syntax , is considered) , and the 
appearance of either of them has no effect whatever on wheth- 
er a symbol in the label field of the macro call gets defined. 
An occurrence of D(0) is replaced by the label field of the 
macro call during expansion; if this field is empty, D(0) 
expands as the null string. In any event, D(0) will be at 
most seven characters long, namely the first six characters 
of the symbol in the label field preceded by '$* if the label 
field begins with a '$'. 

30) Dummy subscripts (including all the subscripts appearing 
between *(' and ')', e.g., e2 and e3 as well as el in 
D(el$e2,e3)) , generated sjnnbol subscripts, and expressions 
between '($' and ')' may be arbitrary NARP expressions. Fur- 
thermore, these expressions may contain references to dummy 
variables, generated symbols, and value-to-digit-string ex- 
pressions. Thus ($4+D(I*D(3))) is legal. 

Any undefined symbols occurring in these expressions are 
treated as defined sjnmbols with the value -1. 
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31) The construct D() no longer expands to all the arguments 
of a macro call, but instead expands to the first argument 
only ( without enclosing parentheses) . To achieve the effect 
that D() has in ARPAS, use D(,) in NARP. 

32) NARP allows more syntactical forms of references to dummy 
variables than ARPAS does. Before describing all the pos- 
sible combinations, a few conventions are convenient: 

a) In th« following, "argument" will refer to the 
character string, as given in the macro call, 
after possible enclosing parentheses have been 
removed . 

b) The number of arguments supplied at the call is 
n (n > 0) . 

c) The number of characters in an argument i is n(ei) , 

d) The structure ei for i an integer stands for an 
expression (its value stands for some argument 
usually, so ei will be used somewhat ambiguously 
to stand for an expression or the value of an 
expression) , 

With the above in mind, we consider the three kinds of 
references to dummy variables: 

i.) D(el) 

This expands to argument el (which may be the null string) , 
where < el < n. 

Special notation: D() = D(l) 

ii.) D(el,e2) 
If el > e2 then this expands to the null string (the range 
of values of el and e2 is arbitrary), otherwise this expands 
to argument el through e2, where o ^ el < e2 < n, with each 
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argumenC enclosed in parentheses and a cotnma Inserted be> 
tween each argument. For example, D(3,3) « (D(3)). 

Special notation: D(,) « D(l,n) 

D(,el) - D(l,el) 
D(el,) - D(el,n) 

ill.) D(el$e2,e3) 

In all cases, < el < n must be true. If e2 > e3 then 

this expands to the null string (range of values of e2 and 

e3 is arbitrary) , otherwise it expands to characters e2 
through e3 of argument el. 

Special notations: D(el$,) = D(el$l,n(el)) 

D(el$,e2) « D(el$l,e2) 
D(el$e2,) « D(el$e2,n(el)) 
D(el$e2) » D(el$e2,e2) 
D(el$) = D(el$l) = D(el$l,l) 
In any of the above six forms, 
el may be missing; if so 1 is 
assumed. 

Note on special notations: A general rule which will help 
in remembering what the special notations mean is the fol- 
lowing: "Whenever an expression is missing from a form, 
the value 1 is assumed, unless the expression is missing 
from a place where an upper bound is expected (as in D(3,) 
or D(3$2,)), in which case the largest "reasonable" value 
is assumed." 

The observant reader will have noted that in the above 
description of the form D(el$e2,e3), no mention was made of 
the bounds of an e2 and e3 in case e2 < e3. This was in- 
tentional, since by choosing e2 and e3 appropriately, sneaky 
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things can be done, although they should not be played with 
lightly since they depend on the implementation of macro 
calls in NARP. When a macro call is made, the arguments 
are laid out in core in one contiguous string, with each 
argument surrounded by parentheses and followed by a comma. 
For example $BETA AMAC (GAMMA) , (_^DELTA^EPSLONj^) , ZETA causes 
the following argument string to be laid out in core: 
($BETA) , (GAMMA) , (^DELTA^EPSLON^^) , (ZETA) , Each argument has 
a pointer associated with it which points to the left pa- 
renthesis preceding the argument, and when a form like 
D(el$e2,e3) is expanded, the values of e2 and e3 are simply 
added to el's pointer, delimiting the string which is to 
replace the dummy reference. By picking el and e3 appro- 
priately, this string may include parts of argument el-1 and 
el+1 (as well as argument el) or even the entire argument 
string. The only restriction on el and e3 is that when 
added to the pointer for el, the resulting pointer must not 
be outside the entire argument string for the macro call. 

Examples: (Assuming the call shown above is being processed) 

D(l$-1,7) = , (GAMMA), 
D(2$-4,4) = MA),(^DEL 
D (2 $18, 21) = ZETA 

D(l$-9,-l) is an error because the -9 points one charac- 
ter to the left of the entire argument string 
D(2$-16 , 23) = ($BETA) , (GAMMA) , (_^DELTA^EPSLON_j^) , (ZETA) , 

Although this feature may have limited uses, it is there for 
the programmer to utilize if he finds a use for it. 

33) The format of an argument given to a macro when it is called 
may be slightly different in NARP than in ARPAS ("may be" 
is intentional, since we have not been able to discover the 
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precise ARPAS format). The essential thing is this: any 
blanks, commas, semicolons, or parentheses occurring between 
single quotes ("between" here means between an "odd-quote" 
and an "even-quote", where the first quote encountered is 
odd, the next is even, etc., thus B and D are between single 
quotes in the following, but A, C, and E aren^t: A'B'C'D'E) 
are'' treated exactly like other characters between single 
quotes, i.e., they do not serve as terminators, separators, 
or the like. In effect, when the argument collector in NARP 
is collecting arguments for a macro call, the occurrence of 
a single quote causes it to stop looking for special charac- 
ters except for quotes (and, of course, carriage return, 
which is an absolute terminator). Thus, in the following, 
when a blank, comma, semicolon, or parenthesis is referred 
to, it is understood that the character is not between single 
quotes . 

The argument string for a macro call has the following format: 

<arg>,<arg>, . . . ,<arg> <terminator> where <terminator> is a 
blank, semicolon, or carriage return. There are essentially 
three forms of <arg>: 

i.) <arg> may be the null string. 
ii.) If the first character of <arg> i£ not a left paren- 
thesis then <arg> is a string of characters not con- 
taining blank, comma, semicolon, or carriage return 
(remember: blanks, commas, and semicolons may appear 
in <arg> if they are between single quotes), 
iii.) If the first character of <arg> ±s^ a left parenthesis, 
then <arg> does not terminate until a blank, comma, 
or semicolon is encountered after the right paren- 
thesis which matches the initial left parenthesis 
("matches" means that all left and right parentheses 
in the argument are noted and paired off with each 
other so that a nested parenthesis structure is pos- 
sible). Of course, a carriage return at any point 
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immediately terminates <arg>. Again, remember that 
blanks, commas, semicolons, and parenthesis between 
single quotes are ignored when <arg> is being de- 
limited. The initial left parenthesis and its match- 
ing right parenthesis (note that this right paren- 
thesis need not be the last character of <arg>) are 
removed from <arg> before it is transmitted to the 
macro. 

Examples: AMAC Cj,;^.,) , , •HOUSE,j^ROGER' 

D(2) is the null string 
D(3) = ' HOUSE ,j^ROGER' 
AMAC , (PAR (STRING •),' PAR) )MORE,AB 
D(l) is the null string 
D(2) = PAR (STRING'), 'PAR) MORE 
D(3) = AB'_^'C 



34) There is no limit on the number of arguments that can be 
given to a macro (except the size of the core, of course). 

35) When constructing a generated symbol, the digit string 
formed is preceded by one zero. Thus the first time 

A MACRO D,G,3 
G(2) NOP 

ENDM 

is expanded, G(2) becomes G02 . The second time it will 
become G05. Since only the first six characters of a 
symbol are meaningful, the user should keep the generated 
symbol very short to avoid nasty problems. A generated 
symbol subscript must be within the range [l,m], where 
m is the upper limit specified in the macro head (note: 
1 < m < 1023 must be true) . 

36) In the value-to-digit-string conversion, if the value is 
negative then the digit string is preceded by a minus sign 
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37) NARG may only appear within a macro body, but it is legal 
within any macro body (i.e., even if no dummy variable was 
specified by a given macro, NARG is still legal within that 
macro and yields the value zero) . 

38) NCHR has been changed so that its operand has precisely the 
samd format as an argument to a macro. Thus, the operand 
ends when a carriage return is encountered, or on the first 
blank, comma, or semicolon not within single quotes unless 
the first character of the operand is a left parenthesis. 
In the latter case, blanks, commas, and semicolons are 
shielded as described above in the discussion of macro argu- 
ments (see 33). By scanning for NCHR and enclosing its 
operands in parentheses, most ARPAS programs can be easily 
converted to NARP programs as far as NCHR is concerned. 

The only case for which this will not work is when the op- 
erand contains unmatched parentheses that are not within 
single quotes. 

39) The RPT option RPT <expression> has been extended to 

RPT <expression>[ ,<increment list>] , where <increment list> 
is of the form (<symbol>=<el>[ ,<e2>] ) (...) ... (...) 
Note, however, that the expression is evaluated before 
the increment list is processed, so its value should not 
depend on symbols initialized in the increment list. 
Example: RPT 4,(J=2,3) 
DATA Jt3 
ENDR 
When expanded results in the following values : 

8 

125 

512 

1331 

The increment list of any RPT or CRPT option may be of any 

length; no limit is set as in ARPAS. 
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40) Symbol definitions and external symbols : 

Symbols are defined in three ways: By being assigned 
values with EQU directives (or equivalently, by appearing 
in an RPT or CRPT increment list), by appearing as labels, 
and by being used with the EXT directive in a certain way. 
Symbols may also be declared as external in two ways, by 
preceding them with $ when they are defined, or by giving 
them as parameters to the directive EXT after they are 
defined. These cases are discussed in greater detail 
below: 

a) Sjmibol defined as a label: If the symbol is already 
defined, either as a label or by EQU, the error mes- 
sage *D* is typed; the old definition is completely 
replaced by the new one. 

b) Sjnnbol defined by EQU: If the symbol is already 
defined as a label than the error message 'D' is 
typed and the old definition is completely replaced 
by the new one; if the symbol is already defined by 
EQU then its value is changed, and if a $ is present 
the s3rmbol is marked as external; the operand of EQU 
must be defined and must have an r factor in the range 
[-15,15]. 

c) Symbol defined by EXT: See e.) below. 

d) Declared external by $: For a label this is obvious; 
for an EQU'ed symbol, a $ need appear only once, suc- 
cessive EQU's of the symbol will preserve the external 
mark . 

e) Declared external by EXT: Two cases: 

i,) EXT has no operand: The symbol in the label 
field is simply marked as external; it must 
be a defined sjmibol, but it may have already 
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been marked as external or may even have 
a $ preceding it. 

ii.) EXT has an operand: The operand must be a 

defined expression; the symbol is immediately 
output as an external symbol with value the 
same as the operand value; no local definition 
of the symbol is made , in fact no table look-up 
or addition to the table occurs. 

Note: ARPAS and NARP output external symbol definitions 
at different times; it is possible that this can have an 
effect on a program if the user has done something kludgy. 
Except for case ii.) under e.) above, NARP outputs no ex- 
ternal definitions until the END directive is encountered. 
ARPAS, however, outputs external definitions as soon as it 
can. Thus, 

$A EQU 3 

A EQU 4 

END 

will cause ARPAS to output an external definition of A 
with value 3, while NARP will output an external definition 
of A with value 4. 

41) it is conceivable that the manner in which undefined ex- 
pressions are handled by NARP could lead to difficulties 
in very obscure cases which are at best vaguely defined 
anyway. When NARP encounters an undefined expression 
which involves more than a single undefined sjnnbol, the 
expression is saved until every undefined symbol in it 
becomes defined. At the moment when this happens, the 
expression is evaluated. 
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Thus 





DATA 

EOU 

EOU 


A + B 


A 





A 


1 


B 


EOU 
END 


2 



will cause a data word of value 3 (not 2) to be output, 

42) Operating NARP: When started, NARP asks for the specifi- 
cation of a source file, an object file, and an optional 
text file. Only one confirmation character is needed, 
namely, a carriage return at the end of the object file 
specification. Then NARP immediately begins processing, 
typing only IDENT*s and error messages until the END 
directive is encountered (don't be surprised when NARP 
types an IDENT immediately after it starts processing; 
remember that it is one-pass). 

At the end of the assembly, a line of the following form 
is typed: 

2 SEC 3 ERRORS 101(65)WORDS (S:413,0:10,L:87,M: 2033,U: 73) 

2 SEC: This is the time required for assembly as measured 

by BRS 88. Timing begins after all files are opened 
and ends before any file is closed. 

3 ERRORS: The number of error messages typed during the 

assembly. 
101(65)WORDS: The value of the location counter when the 
END directive is encountered (first in octal, then 
in decimal) , 
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S:413 413 symbols in the symbol table. 

0:10 10 programmer -de fined opcodes (excluding macros) 
in the opcode table 

L:87 87 literals in the literal table 

M:2033 2033 machine words of defined macros 

U:73 73 words of undefined expressions in expression 
table (currently this is the maximum size 
attained by the undefined expression table 
during the assembly; there is as yet no garbage 
collection for this table) . 

43) The three most important tables in NARP are the main table 
(which contains all symbols, opcodes, and literals, each 
occupying 4 words per entry), the string storage (which 
contains all macro definitions and is used for storing 
repeat? blocks and argument strings to macros; characters 
are packed 3 to a word) , and the undefined expression 
table. Currently these tables have the following sizes: 

(1250 entries) 



main table 


5000 


as 


2250 


expr table 


900 



Using these figures and the information printed out at the 
end of an assembly, the user can see how close he is to 
overflowing the tables (remember that there are 191 pre- 
defined opcodes in the main table, so the user, can only 
create 1059 new entries). Currently there is no garbage 
collection in the string storage, 

44) At the end of an assembly, after typing the line of infor- 
mation mentioned above, all undefined symbols are listed. 



X-1 



1.0 Introduction 

HARP (new ARPA S) is a one -pass assembler for the SDS S^O 
with literal, subprograjn, conditional assembly, and macro 
facilities. The source language for NAEP, primarily a one-for- 
one representation of machine language written in symbolic form^ 
Is very similar to that for ARPAS (another assembler for the 9^0), 
but there are notable exceptions making it necessary to do a 
certain amount of transliteration to convert an ARPAS program to 
a MRP program. No further mention will be made of ARPAS 
in this manual; for more details see ARPAS, Reference Manual for 
Time-Sharing Assembler for the SDS 930 , Doc. No. R-26, 
February 2k, I967. 

To motivate the various facilities of the assembler, the 
following pseudo-historical development of assembly languages 
is presented. 

1.1 Pseudo-history of assembly languages 

A program stored in the main memory of a modern computer 
conjsists of an array of tiny circular magnetic fields, some 
oriented clockwise, others oriented counterclockwise. Obviously, 
if a programmer had to think in these terms when he sat down 
to write a program, few problems of any complexity would be 
solved by computers, and the cost of keeping programmers sane would 
be prohibitive. To remedy this situation, utility programs 
called assemblers have been developed to translate programs 
from a symbolic form convenient for human use to the rather 
tedious bit patterns that the computer handles. At first these 
assemblers were quite primitive, little more than number converters, 
in fact. Thus, for example: 

Tag Opcode Address 



76 00^0J^ 
P 55 00^01 
35 00^02 
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would be converted into three computer Instructions which. would 
add together the contents of cells kfi^ and k^l and place the 
result in cell k^. An assembler for doing this type of conver- 
sion Is trivial to construct . 

After a time, some irritated programmer who could never 
remember the numerical value of the operation "load the A register 
with the contents of a cell of memory" decided that it would not 
be too difficult to write a more sophisticated assembler which 
wo\ild allow him to write a short mnemonic word in place of the 
number reprosenting the hardware operation. Thus, the sequence 
of instructions shown febove became: 

LDA 001|JZ50 
ADD 00^01 
STA 00U02 

This innovation cost something, however, namely the assembler 
had to be more clever. But not much more clever. The prograjnmer 
in charge of the assembler simply added a table to the assembler 
which consisted of all the mnemonic operation names ( opcodes ) 
and an associated number, namely the numerical value of the 
opcode. When a mnemonic name, say 'ADD*, was encountered by the 
assembler during the conversion of a program, the opcode table 
was scanned until the mnemonic name v/as found; then the associated 
numerical value (in this case, 55) was used to form the instruc- 
tion. Within a month, no programmer could tell you the numerical 
value of XMA. 

In a more established field, the innovation of these mnemonic 
names would have been quite enough for many years and many 
theoretical papers. However, programmers are an irritable lot, 
and furthermore, are noted for their ability to get rid of sources 
of irritation, either by writing more clever programs or by 
asking the engineers to refrain from making such awkward machines. 
And the use of numbers to represent addresses in memory was a 
large source of irritation. To see this we need another example: 



CIA 

LDX 00400 
2 STA 0ifc07 
BRX 00300 



1-3 

Assuming cell hpji contains -7, this sequence stores zeroes in 
cells 500 through 5^ provided that the sequence is loaded in 
memory so that the STA instruction is in cell 3^0 (otherwise, 
the BRX instruction would have to be modified). This was the 
crux of the problem: Once a program was written, it could only- 
run from a fixed place in memory and could only operate on fixed 
cells in memory. This was especially awkward when a program was 
changed, since inserting an instruction anywhere in a program would 
generally require changes in many, many addresses. One day a 
clever progi'ammer saw that this problem could be handled by a 
generalization of the scheme used to handle opcodes, namely, 
let the programmer use symbolic names ( symbols ) for addresses 
and have the assembler build a table of these symbols as they 
are defined and then later distribute the numerical values 
associated vrith the symbols as they are used. Thus the example 
becomes: 

CLA 

LDX TABLEN 

LOOP STA TABEND,2 

BRX LOOP 

(Note that at the same time the programmer decided to move 

the tag field to after the address field (simply for the sake 

of readability) and to even dispense with it entirely in case 

it was zero. ) The assembler now has two tables, the fixed opcode 

table with predefined names in it, and a symbol table which is 

initially empty. There is also a special cell in the assembler 

called the location counter (LC) which keeps track of how many 

cells of program have been assembled; LC is initially zero. 

There is another complication: In the above example, when the 

symbol TABLEN is encountered, it may not be defined yet, so the 

assembler doesn't know what numerical value to replace it with. 

There are several clever ways to get around this problem, but 

the most obvious is to have the assembler process the program 

to be assembled twice . Thus, the first time the assembler scans 

the program it is mainly interested in the symbol definitions 

in the left margin (a symbol used to represent a memory address 

is called a label ) . In our example, when LOOP is encountered, 

it is stored in the symbol table and given the value 2 (because 



CIA 




LDB 


EiGirr 


LDX 


TABLEN 


STP 


TABEND, 2 


EAX 


1,2 


BRX 


LOOP 
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it is preceded by two cells; remember that LC keeps track of 
this). At the end of pass 1, all symbols defined in the program 
are in the symbol table with numerical values corresponding to 
their addresses in the memory. So when pass 2 begins, the symbol 
table is used exactly as the opcode table is used, namely, when, 
for example, LOOP is encountered in the BRX instruction above, 
it is looked up in the symbol table and replaced by the value 2. 
If the prograiti should later be changed, for example to 



LOOP 



then the assembler will automatically fix up LOOP to have the 
value 3 (because of the inserted LDB instruction) and will 
convert BRX LOOP to BRX 3 instead of to BRX 2 as before. Thus, 
the programmer can forget about adjusting a lot of numerical 
addresses and let the assembler do the work of assigning new 
values to the symbols and distributing them to the points where 
the symbols are used. In addition to the greater flexibility 
achieved, symbols with mnemonic value can be used to make the 
program more readable. 

The use of symbols to stand for numerical values which 
are computed by the assembler and not the programmer is the basic 
characteristic of all assembly languages. Its inception was 
a fundamental breakthrough in machine language programming, dispensing 
with much dullness and tedium. And a new breed of programmer 
was born: the assembler -writer. To justify his existence, the 
assembler-writer began to add all sorts of bells and whistles 
to his products; the primary ones are discussed in the next 
section (with reference to NARP) . 

1.2 Assembly languages: some basic constituents and concepts 

^ Times: assembly time: when a program in symbolic form is 

converted by an assembler to binary 
(relocatable) program form. 
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load time: when a binary program is converted by a loader to 
actual machine language in the main memory of 
the computer. 

rum time: when the loaded program is executed. 

assembler ^. loader ^ ^^ . 
source program — > binary program > object program 

Expres<ions ; The idea of using a symbol to stand for an address 
Is generalized to allow an arithmetic expression (possibly 
containing symbols) to stand for an address. Thus, some calcu- 
lations can be performed at assembly time rather than at run 
time, making programs more efficient. 

Literals ; Rather than writing IDA 141 and somewhere else defining 
Ml to be a cell containing -1, the literal capability allows the 
programmer to write the contents of a cell in the address field 
instead of the address of a cell. To indicate this, the expression 
is preceded by *=*. The assembler automatically assigns a ceU 
for the value of the expression (at the end of the program): 

CIA 

LDB =8 

LDX =-l6*2 

LOOP STP TABBEG+l6*2,2 

EAX 1,2 

BRX LOOP 

Relocation : A relocatable program is one in which memory locations 

have been computed relative to the first word or origin of the 

program. A loader (for this assembler, DDT) can then place the 

assembled program into core beginning at whatever location may be 

specified at load time. Placement of the program involves a 

small calculation. For example, if a memory reference is to the 

nth word of a program, and if the program is loaded beginning 

at location k, the loader must transform the reference into 

absolute location n+k. This calculation should not be. done to 

each word of a program since some machine instructions (shifts, 

for example) do not refer to memory locations. It is therefore 

necessary to inform the loader whether or not to relocate the 

address for each word of the program. Relocation information is 

determined automatically by the assembler and transmitted as a 

relocation factor ( rfactor ). Constants or data may similarly 
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require relocation, the difference here being that the relocation 
calculation should apply to all 2h bits of the 9U0 word, not just 
to the address field. The assembler accounts for this difference 
automatically. 

Subprograms and external symbols : Programs often become quite 
large or fall into logical divisions -which are almost indei)endent . 
In either case it is convenient to break them into pieces and 
assemble (and even debug) them separately. Separately assembled 
parts of the lame program are called subprograms (or packages ). 
Before a program assembled in pieces as subprograms can be run it 
is necessary to load the pieces into memory and link them. The 
symbols used in a given subprogram are generally local to tiiat 
subprogram. Subprograms do, however, need to refer to symbols 
defined in other subprograms. Tlie linking process takes care of 
such cross references . ' Symbols used for it are called external 
symbols . 

Directives : A directive (pseudo-opcode is a message to the 
assembler serving to change the assembly process in some way. 
Directives are also used to create data: 

LIST 

MESSAGE TEXT 'THIS IS A PIECE OF TEXT' 
START LDA ALPHA 

The LIST directive will cause the program to be listed during 
assembly, while the TEXT directive will cause the following text 
to be stored in memory, four characters to a word. 
Conditional assembly ; It is frequently desirable to permit the 
assembler to either assemble or skip a block of statements 
depending on the value of an expression at assembly time; this 
is called conditional assembly . V7ith this facility^ totally 
different object programs caji be generated, depending on the values 
of a few parameters. 

Macros ; A macro is a block of text defined somewhere in the 
program and given a name. Later references to this name cause 
the reference to be replaced by the block of text. Thus, the 
macro facility can be thought of as an abbreviation or shorthand 
notation for one or more assembly language statements. The macro 
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facility is more powerful than this, however, si. e a macro me/ 
have formal arguments which are replaced by actu. :. ar^-juents v:hei 
the macro is called. 

One-pass assembly : Instead of processing a sourc.3 pr^ ;ram tv7ice 
as was described above (section 1.1), NARP accom^. ^ishe , the same 
task in one scan over the source program. The mc ::hod . sed is 
rather complex and is not described in this docuuc^nt. 
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2.0 Basic constituents of NAPP 

2.1 Character set 

All the characters listed in Appendix B have meaning in 
NARP except for *?* and ' V^*. The following classification of 
the character set is useful: 



1 

letter : 


A-Z^ 


octal digit: 


0-7 


digit: 


0-9 


alphanumeric character: 


letter or digit or colon 


terminator : 


, ; blank CR (denotes carriage return) 


operator : 


!# ^ &* + -/<=> @ t 


delimiter: 


" $ • ( ) [ ] . - 



The multiple -blank character (l35o) niay appear anyi^here that a 
blank is allowed. All characters with values greater than 77q are 
ignored except for multiple -blank character (l35o) and carriage 
return (l55o)' 

2.2 Statements and format 

Tlie logical unit of input to NARP is the" statement, a sequence 

of characters terminated by a semi-colon or a carriage return. 

Tliere are five kinds of statements : 

empty: A statement may consist of no characters at all, or only 
of blank characters. 

comment : If the very first character of a statement is an 
asterisk, then the entire statement is treated as a 
comment containing information for a human reader. 
Such statements generate no output. 

The format for the next three kinds of statements is split into 

four fields: 

label field : This field is used primarily for symbol definition; 
it begins with the first character of the statement and 
ends on the first non-alphanumeric character (usually a 
blank). 
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opcode field : This field contains a directive name, a macro 
name, or an instruction (i.e., any opcode other than a 
directive or macro). The field begins with the first 
non-blank character after the label field and terminates 
on the first non-alphanumeric character; legal terminators 
for this field are blank, asterisk, semi-colon, and 
carriage return. 

operand field : The operand for an instruction, macro, or 

directive appears in this field, it begins with the first 
non-blai k character following the opcode field and terminates 
on the first blank, semi-colon, or carriage return. Note 
that a statement may terminate before the oi)erand field. 

comment field : This field contains no information for MARP but 
may be used to help clarify a program for a human reader. 
The field starts with the first non-blank character after 
the operand field (or after the opcode field if the opcode 
takes no operand) and ends on a semi-colon or carriage return. 

Now we continue describing the kinds of statements : 

instruction: If the opcode field of a statement does not contain 
a directive name or a macro name, then the statement is 
an instruction. An instruction usually has an expression 
as an operand and generates a single machine word of 
program. See section 3 for a detailed description of 
instructions. 

directive: If a directive name appears in the opcode field, then 
it is a directive statement. The action of each directive 
is unique and thus each one is described separately (in 
Section k) . 

macro: A macro name in the opcode field of a statement indicates 
that the body of text associated with the macro najne should 
be processed (see section 5)' 

Example of various kinds of statements: 

* FOLLOWING ARE TV/0 DIRECTIVES (MACRO, ENDM) WIIICH DEFINE 

* THE MACRO SKAP 

SKA? MACRO; SKA =UB7; EKDM 
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* NOW SKAP IS CALLED: 

LDA ALPHA 

SKAP; BRU BAD IF NEGATIVE THEN ERROR 
OKAY ADD BETA NOW A=ALHiA+BETA; BRU GOOD 



In subsequent sections the details of instructions, directives, 
and macros will be explained, but first some basic constituents 
and concepts common to all of these statements will be discussed. 

2,3 Symbols^ numbers, and string constants 

Any string of alphanumeric characters not forming a number 
is a symbol, but only the first six characters distinguish the 
symbol (thus QI23H5 is the same symbol as QX2'^k'^6) . Note that 
a symbol may begin with a digit, and that a colon is treated as 
a letter (as a matter of good programming practice, colons should 
be rarely used in symbols, although they are often useful in 
macros and other obscure places to avoid conflicts with other 
names). In the next section the definition and the rfactors 
of symbols are discussed. 

A number is any one of the follov/ing: 

a) A string of digits 

b) A string of digits follov^ed by the letter *D* 

c) A string of digits followed by the letter 'B' 

d) A string of digits followed by the letter *B' 
follov/ed by a single digit. 

A D-suffix indicates the number is decimal, whereas a B-suffix 
indicates an octal nianber. If there is no suffix, then the 
current radix is used to interpret the number (the current 
radix is initially 10 but it may be changed by the OCT and DEC 
directives). If the digit 8 or 9 is encountered in an octal 

number, then an error message is typed. If the value of a 

23 
number exceeds 2 -1 overflow results; HARP does not check for 

this condition, and in general it should be avoided. A B-suffix 
followed by a digit indicates an octal scaling; thus, 7UB3=7^000B. 
Examples : 

symbols : START m CALCULATE lllD2 li^BlO 
numbers: 1^^ I8D 77 3B 777B5 13B9 
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A string constant is one of the following: 

a) A string of 1 to 3 characters enclosed in double 
quotes ("). 

b) A string of 1 to if characters enclosed in single 
quotes (')• 

In the first case the characters are considered to be 8 bits 
each (thus only 3 can be stored in one machine word), while in 
the second case they are considered to be 6 bits each. In both 
cases, strings of less than the maximum length (3 or U, as the 
case may be) are right- justified. Thus 

tAt _ I A» - ^fA" ~ " A" 
/i - ijjt,*^ - /i - j^^K 

where ^ denotes a blank. If a string constant is too long, then 
an error message is typed and only the first 3 (or k) characters 
are taken. Normally string constants are not very useful in 
address computation, but are most often used as literals: 

LDA WORD 
SKE ='G0» 
BRU STOP 

Both numbers and string constants are absolute, i.e., their 
rf actor is zero. 

2,h Symbol definitions 

Since MRP is a one-pass assembler, the statement that a 

symbol or expression is "defined" usually means that it is defined 

at that instant and not somewhere later in the program. Thus, 

assuming ALHIA is defined nowhere else, the follovring 

BETA EQU ALPHA 
ALPHA BSS 3 

is an error because the EQU directive demands a defined operand 
and ALPHA is not defined until the next statement. This convention 
is not strictly adhered to, however, since sometimes the state- 
ment "XYZ is not defined" will mean that XYZ is defined nowhere 
in the program. 

A symbol is defined in one of two ways : by appearing as a 
label or by being assigned a value with an EQU directive (or 
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equivalent ly, by being assigned a value by NARG, NCHR, EXT 
(see below) J or by being used in the increment list of a RPT 
or CRPT statement). The latter type of symbols are called 
equated symbols. 

Labels t If a symbol appears in the label field of an 

instruction (or in the label field of some directives) 
then it is defined with the current value of the location 
counter (rfactor-l). If the symbol is already defined, 
either as a label or as an equated symbol, the error 
message '(Symbol) REDEFINED' is typed and the old 
definition is completely replaced by the new one. 

Equated symbols: These symbols are usually defined by EQU, 

getting the value of the expression in the operand field 
of the EQU directive. This expression must be defined 
and have an r factor in the range [-15,15]. If the symbol 
has been previously defined as a label, then the error 
message '(Symbol) REDEFINED' is typed and the old definition 

is completely replaced by the new one; if the symbol has already been 
defined as an equated symbol, then no error message is 
given, but the old va3.ue and rf actor are replaced by the 
new ones. Thus, an equated symbol can be defined over 
and over again, getting a new value each time. 

A defined sjmibol is always local, and may also be external. 
If a symbol in package A is referred to from package B, it must 
be declared external in package A. This is done in one of the 
following ways: 

Declared external by $: If a label or equated symbol is 

preceded by a $ when it is defined, then it is declared external. 

$LABEL1 im ALim 

IABKL2 STA BETA LABEL2 IS LOCAL ONLY 

^GM/^Ak EQU DELTA 
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Declared external by the EXT directive: There are two cases: 

l) EXT has no operand: The symbol in the label field is declared 

external; it must be a defined symbol, but it may have already 

been declared external or may even have a $ preceding it. 

li) EXT has an operand: This case is treated exactly like the 

case: $label EQU operand. 

Certain symbols are pre-defined in NARP, i.e., they already 

have values when an assembly begins and need not be defined by 

the programme.': 

:ZERO: This is a relocatable zero (i.e., value = 0, rf actor = l) 

:LC: This symbol is initially zero (rfactor=l) and remains 

so until the END directive is encountered and all literals 

are output, at which time it gets the value of the location 

counter. See the description of FREEZE for a discussion 

of the use of this symbol. 

Syntactically this is not a symbol, but semantically 

it acts like one. At any given moment, * has the value 

of the location counter (rf actor =l), and can thus be used 

to avoid creating a lot of local labels. 

Thus CIA; LDX lENGTH 

LOOP STA TABLE, 2; BRX LOOP 

can be written as 

CLA; LDX LENGTH; STA TABLE, 2; BRX *-l 

If a given symbol is referred to in a program, but is not 

defined when the END directive is encountered then it is assumed 

that this symbol is defined as external in some other package. 

Whether this is the case cannot be determined until the various 

packages have been loaded by DDT. Such symbols are called 

"undefined symbols" or "external symbol references. " It is 

possible to perform arithmetic upon them (e. g. , LDA UNDEF+1); 

an expression in post-fix Polish form will be transmitted to DDT. 
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2-5 Expressions and literals 

Loosely speaking, an expression is a sequence of constants 
and symbols connected by operators. Examples: 
100-2-XABC/ [ ALPHA+BETA ] 
GAMMA 
F>=Q 
Following is the formal description (in Backus normal form) 
of a NARP expression: 

<primary>: :=<na'nber>|<string constant>|<symbo]>[ •^|[<expr2>] 
<exprl>: :=<primary> <primary> <binary op€rator> <exprr> 
<expr2>: :=<expr]>|<unary operator> <exprl> 
<expressiori>: :=<expr2>|<literal operator> <expr2> 

<binary operator> : : =t | -^ /|+ -|<|<=l = l# >=|>|&-.|l|^ 
<unary op€rator> : : =+ 1 - | 6* 
<literal operator>::= = 

The main point of the above syntax is that two operators 
may never be adjacent (except for a unary operator following a 
literal operator), so A &(?B is illegal (write it as €-^6 & A). 
The literal operator is rather special, only being allowed to 
appear once in a given expression, and only as the first character 
of the expression. Literals are discussed in greater detail 
below. 

The value of an expression is obtained by applying the 
operators to the values of the constants and symbols, evaluating 
from left to right except when this order is interrupted by the 
precedence of the operators or by square brackets*([ ] ); the 
result is interpreted as a 2l+-bit signed integer. The following 
table describes the various operators and lists their precedences 
(the higher the precedence, the tighter the operator binds its 
operands ) : 



'''not parentheses! 
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Operator 



Precedenct 



t 


6 


« 


5 


/ 


5 


+ (u) 


k 


- (u) 


k 


+ 


k 


- 


k 


< 


3 


<= 


3 


s= 


3 


# 


3 


>= 


3 


> 


3 


(^(u) 


2 


& 


1 


1 





i 






Comment 

exponentiation; exponent must be > 

multiplication ~ 

integer division 

unary plus 

negation 

addition 

subtraction 

less than 

less than or equal to 

equal to 

not equal to 

greater than or equal to 

greater than 

logical not 

logical and 

logical or 

logical excJ-usive or 



result of operation is 
if relation is false, 
otherwise 1 



logical operation 
applied to all 
2k bits 



The rfactor of an expression is computed at the same time 
the value is computed. There are constraints, however, on the 
rf actors of the operands of certain operators, as shown in the 
table below: (Note: Rl is a symbol V7ith an rfactor of 1, R2 
is a symbol with an rfactor of 2) . 



operator 


relocation factor (s) 
of operand(s) 


relocation factor 
of result 


exapiples 


t 

& : 

1 


all operands absolute 


absolute 


2Tlf=l6, 
Fit 1( error) 

7&3=3, 
6&Rl(error) 

V2=2, 
Rl/l (error) 


* 


at least one rfactor 
must be absolute, the 
other is arbitrary 


found by multi- 
plying the value 
of the absolute 
operand tiroes the 
rfactor of the 
other operand 


3*R2 has 
rfactor of 6, 
Rl*Rl(error) 


< <= « 


arbitrary relocation 
factors, but must be 
equal 


absolute 


Rl'Rl is true 
R2>Rl(error) 


+ 

(unary and 
binary) 


arbitrary rfactors 


found by applying 

operator to the 
relocation factors 

of the operands 


R1+R2 has 
relocation 
factor of 3 
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The final r factor of an expression must be in the range 

[-8191, 8191]. 

If an expression contains an undefined symbol or if it is a 
literal, then the entire expression is undefined. 

Although a literal is a special kind of expression, it is 
often convenient to think of it as a quite separate entity. The 
use of' literals is discussed below. 
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Programmers fi-equently write such things as 

iM five: 

where FIVE is the name of a cell, containing the constant 5 . The 
programmer must remember to include the datum FIVE in his program 
somewhere. This can be avoided by the use of a literal. 

LDA ==5 

will automatically produce a location containing the correct 

constant in the program. Such a construct is called a literal. 

When a literal is encountered, the assembler first evaluates the 

expression and looks up its value in a table of literals constructed 

for each subprogram. If it is not found in the table, the value 

is placed there. In any case the literal itself is replaced by 

the location of its value in the literal table. At the end of 

assembly the literal table is placed after the sub-program. 

The following are examples of literals: 

=10 =Ub6 =ABC*20-DEF/12 ='HELP' 

=2>AB (This is a conditional literal. Its value will 
be 1 or depending on vrtiether 2>AB at assembly 
time.) 

Some programmers tend to forget that the literal table 

follows the subprogram. This could be harmful if the program 

ended with the declaration of a large array using the statement 

ARRAY BSS 1 

It is not strictly correct to do this, but some programmers 

attempt it anyway on the theory that all they want to do is to 

name the first cell of the array. The above statement will do 

that, of course, but only one cell will be reserved for the 

array.. If any literals were used in the subprogram, they would 

be placed in the following cells which now fall into the array. 

This is, of course, an error. Other than this exception, the 

programmers need not concern himself with the locations of the 

literals . 
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2.6 Opcode classification 

As mentioned above, there are three types of opcodes: 
directives, macros, and instructions (those opcodes which are 
neither directives nor macros). Aside from its type, each opcode 
has a class which indicates whether it takes an operand. 

class 0: operand optional (e.g., NOP, EXT) 

class 1: no operand (e.g., CIA, DEC) 

class 2: operand required (e.g., ADD, DATA) 
Note that for class opcodes, if the operand is missing, then 
the comment field must be empty because otherwise the first item 
in the comment field will be taken as an operand: 

NOP THIS IS A Ca^^MENT 

is the same as 

NOP THIS 
causing THIS to be treated as a symbol. To get around the 
problem, write 

NOP THIS IS A CQMMENT 
On the other hand, class 2 opcodes have no operand field at all: 

CIA THIS IS A CCMIENT 

Although there are instructions and directives of all three 
classes, there are no class 2 macros. 
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3.0 Instructions 

There are three different syntactical forms of instruction 
statements, depending on the class of the instruction in the 
opcode field: (in the following, syntactical elements enclosed 
in square bra,ckets are optional; they may or may not be present.) 

class 0: [[$]lahel] opcodef-] [ operand [, tag] [comment]] 

class 1: [[$] label] opcode [*] [coiffinent] 

class 2: [[.$] label] opcode [■»^] operand[,tag] [comment] 



Each of the syntactical elements is discussed below: 

$ : A label preceded by a dollar sign is declared external 
(see section 2.k). 

label : The label is defined with the current value of the 
location counter (rfactor=l) . 

opcode : The opcode must be either an instruction which is 

already defined or a number. If it is a number, then 
the value (mod 2 ) of the number is placed in bjz5-b8 
(bit through bit 8) of the instruction, and it is 
treated as a class opcode (i.e., operand optional). 

* : If an asterisk follows iramedie,tely after the opcode 

then b9 (the indirect bit) of the instruction is set. 

operand: The operand is an expression which may or may not be 

defined and which has any rf actor. The expression may 

be preceded by '/* or *«-* (or both in any order); 

these characters cause the following bits to be set: 

/ bl (index bit) 

«~ b9 (indirect bit) 

Thus: 

LDA /VECTOK is the same as LDA VECTOR, 2 
STA ^^POWTKR is the same as STA* POINTER 
LDA ^cmFISX. is the seme as LDA* CaMPDC,2 
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tag : The tag is an expression which must be defined and 
absolute. Its value (mod 2"^) is placed in b^b2 of 
the instruction. 

cotanent: The comment does not affect the instruct i<»i generated; 
it may be listed. 

In addition to its class^ a given opcode is designated as 
being either a shift instruction or a non-shift instruction. 
This has nothing to do with whether the action of the instruction 
involves shifting, but is simply a way of distinguishing between 

two kinds of instructions. For non-shift instructions, operands 

Ill- 
are computed mod 2 , while for shift instructions there are two 

possibilities : 

a) If the indirect bit is set by *** or '♦-*, then the value 
of the opcode is trimmed so that blO-b23 are zero, and 
then the instruction is treated as if it were a non- 
shift instruction. 

b) If the indirect bit is not set as above, then the 

9 
operand is computed mod 2^; it must be defined amd 

absolute. 
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k,0 Directives 



There are many directives in MRP; although some of them are 
similar, each in general has its own syntax. Following is a 
concise svcnmary: 



Class 



Directive Use or Function 



Mnemonic for instructions: COPY 



Mnemonic for RCH 



Section 



h.k 



Data generation 



: DATA 
ASC 

TEXT 



Generate data k,^ 

Generate text 

(3 characteri'per word) *4-.l 

Generate text {h 

characters per word) 4.23 



Value declaration 



Assembler control 



: EQU 


Equate a symbol to 






a value 


h.9 


EXT 


Define a symbol as 






external 


U.IO 


NARG 


Number of arguments 


5.5 


NCHR 


Number of characters 


5.5 


OPD 


Define an opcode 


U.17 


POPD 


Define a programmed 






operator 


U.19 


: BES 


Block ending symbol 


k.2 


BSS 


Block starting symbol 


h.3 


END 


End of assembly 


k.8 


DEC 


Intearpret integers 






as decimal 


k,6 


OCT 


Interpret integers 






as octal 


If.l6 


FRGT 


Do not output a 






specific symbol 


U.12 


IDENT 


Identification of 






a i)ackage 


1^.13 
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Class 



Directive 



Use or Function 



b C: C. L- i. C 11 



DELSYM 


Do not output any 








symbols 


4. 


,7 


RELORG 


Assemble relative 








with absolute origin 


4. 


,20 


RETREL 


Return to relocatable 








assembly 


- 4, 


.22' 


FREEZE 


Preserve symbols, 








opcodes, and macros 


4. 


.11 


FIILIB 


Assemble FORTRAN II 








library routines 


4. 


,105 


GLOBAL 


Reverse meaning of $ 








and EXT 


4. 


,128 


LOCAL 


Reset meaning of $ 








and EXT 


4. 


.143 



Output and listing 
control 


: LIST 




' NOLIST 




REM 


Conditional assembly 
and macros 


: IF 


- 


ELSF 




ELSE 




ENDF 




RPT 




CRPT 




ENDR 




MACRO 




LMACRO 




ENDM 



Set listing controls 4.14 
Reset listing controls 4.15 
Type out remark 4.21 



Begin if body 


5. 


1 

1 a. 


Alternative if body 


5, 


.1 


Alternative if body 


5. 


,1 


End if body 


5. 


.1 


Begin repeat body 


5. 


.2 


Begin conditional 






repeat body 


5. 


.2 


End repeat body 


5. 


^2 


Begin macro body 


5. 




Alternative to MACRO 


c 


.4 


End macro body 


5, 


.4 



In the remainder of this section, all directives listed above 
except for those associated with conditional assembly and macros 
are described. \ 
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k.X ASC Generate text (3 characters per word ) 

[[$]label] ASC string [conment] 

This directive creates a string of 8-bit characters stored 
3 to a word, fhe string starts in the leftmost character of a 
word and takes up as many words as needed; if the last word Is 
not filled up completely with characters from the string, then 
the right end of the word is filled out with blanks. If a label 
appears, its value is the address of the first word of the 
string. The syntactical element "string" is usually any 
sequence of characters (not containing a single quote) siirrounded 
by single quotes. However, the first character encountered 
after *ASC' is used as the string delimiter (of course, blanks 
and semi-colons cannot be used as string delimiters). 



Examples: 



ASC 'NO SINGLE QIX)TES, HERE IS A SEMI-COIJON : ; ' 
$ALPHA ASC $I-1ERE IS A SINGLE QUOTE: ♦$ 



k,2 BES Block ending symbol 

[[$] label] BES expression [comment] 

The location counter is incremented by the value of the 
expression in the operand field and then the label (if present) 
is given the new value of the location counter. Thus, in 
effect, a block of words is reserved and the label addresses 
the first word after the block. The expression must be defined 
and absolute. This directive is most often used in conjunction 
with the BRX instruction, as in the follovring loop for adding 
together the elements of an, array: 

LDX =- LENGTH; CLA; ADD ARRAY, 2 
BRX *-l; STA RESULT; HLT 
ARRAY BES LENGTH 



^•3 BSS Block starting symbol 

[[$] label] BSS expression [comment] 

This directive does exactly the same thing as BES except that 
the label (if present) is defined before the location counter 
is changed. Thus, the label addresses the first word of the 
reserved block. It should be noted that the expression for both 
BES ajid BSS may have a negative value, in which case the location 
counter is decremented. 



k,h COPY Mnemonic for RCH 

[[$]label] COPY 8^,s^,s ,... [comment] 

(where s. are symbols from a special set associated with the 
COPY directive) 

The COPY directive produces an RCH instruction. It taikes 
in its operand field a series of special symbols, each standing 
for a bit in the address field of the instruction. The bits 
selected by a given choice of symbols are merged together to 
form the address. For example, instead of using the instruction 
CAB (0^60000U), one could vrrite COPY AB. The special symbol 
AB has the value 0000000^. 

The advantage of the directive is that unusual combinations 
of bits in the address field — those for which there exist 
normally no operation codes --may be created quite naturally. 
The special symbols are mnemonic 3 for the functions of the 
various bits. Moreover, these s;yTnbol3 have this special meaning 
only when used with this directive; there is no restriction on 
their use either as symbols or opcodes elsewhere in a program. 
The symbols are : 

Symbol Bit Fu nction 



A 


23 


Clear A 


B 


22 


Clear B 


AB 


21 


Copy (A) -* B 


BA 


20 


Copy (b) -»A 


BX 


19 


Copy (b) -> X 


XB 


18 


Copy (X) -* B 


E 


17 


Bits 15-23 (exponent part) only 


XA 


16 


Copy (X) ^A 


AX 


15 


Copy (A) ->X 


N 


Ik 


Copy -(A) -^ A (negate A) 


X 


1 


Clear X 



To exchange the contents of the B and X registers, negate A, 
and only for bits 15-23 of all registers, one would write 
COPY BX,XB,N,E 
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If. 5 DATA Generate data 

[[$] label] DATA e^jegjC^,... [conoment] 

The DATA directive is used to produce data in programs. 
Each expression in the operand field is evsuLuated and the 2U-bit 
values assigned to increasing memory locations. One or more 
expressions may be present. The label is assigned to the 
location of the first expression. The effect of this directive 
is to create a list of data, the first word of which may be 
labeled. 

Since the expressions are not restricted in any way, any 
type of data can be created with this directive. For example: 

DATA 100,-217B,START,AB^/DEF, 'NUTS » ,5 
creates six words. 



U.8 
^.6 lEC Interpret integers as decimal 

EEC [comment] 

The radix for integers is set to ten so that all foUowinsr 
integers (except those with a B- suffix) are interpreted as 
decimal, "hen an assembly begins the radix is initialized to 
ten, so DEC need never be used unless the OCT directive is used. 



U.9 

^•7 DELSYM Do not output any symbols 

DELSYM [comment] 

If DELSYM appears anywhere in a program being assembled, 
the symbol table and opcode definitions will not be output 
by KARP when the END directive is encountered. The main purpose 
of this directive is to shorten the object code generated by 
the assembler, especially when the symbols are not going to 
be needed later by DDT. 
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4. 8 END End of assembly 

END [ comment] 

When this directive is encountered the assembly of the current 
program terminates. If the LIST directive has been used then various 
information may be listed, for example undefined symbols. 



U.9 EQU Equate a symbol to a value 

[$] symbol EQU expression [comment] 

The symbol is defined with the value of the expression; if 
the symbol is already defined, its value and rf actor are changed. 
The expression must be defined and must have an rf actor in the 
range [-15,15]' If the symbol has been declared external before 
or if it has been forgotten (using FRGT) then EQU preserves this 
inf ormat ion . Thus 



$ALHm EQU h 
ALHIA EQU 3 



will cause ALFIIA. to be declared external but with a value of 
three at the end of the assembly (provided ALPHA, is not changed 
again before the EIJD directive). See section 2,k for more 
discussion of EQU. 
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I*. 10 EXT Define a symbol as external 

[$] symbol EIXT [expression [comment]] 

This directive is used to declare symbols as external. See 
section 2,k for a discussion of the various cases. 
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4.105 FIILIB FORTRAN II Library Routines 

FIILIB [comment] 

Causes an end- of -program word (31062144B) to be outputted between 
each program in a multiple program assemble. This allows the resul- 
tant object file to be loaded by the FORTRAN II load. The directive 
need only appear in the first program of the multiple program assembly. 
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^.11 FREEZE Preserve symbols, opcodes, and macros 

FREEZE [comment] 

Sometimes subprograms share definitions of sjinbols, opcodes, 
and macros. It is possible to cause the assembler to take note 
of the current contents of its symbol and opcode tables and the 
currently defined macros and include them in future assemblies, 
eliminating the need for including copies of this information 
in every subprogram's source language. 

When the FREEZE directive is used, the current table 
boundaries for symbols and opcodes and the storage area for macros 
is noted and saved away for later use. These tables may then 
continue to expand during the current assembly. (A separate 
subprogram may be used to make these definitions; it will then 
end with FREEZE; END.) The next assembly may then be started 
with the table boundaries returned to what they were when FREEZE 
was last executed. This is done by entering the assembler 

at its "continue" entry point, i.e., by typing in the EXECUTIVE 

CONTINUE 

Note that the assembler cannot be released (i.e., another 

subsystem like QED or DDT cannot be used) without losing the 

frozen information. 

In conjunction with the FREEZE directive, the predefined 

symbol :LC: is useful, especially when writing large 

re-entrant programs. Following is a three -package program 

using FREEZE and :LC:. 

PI IDENT 

<definitions of macros, opcodes, and global equated 

symbols 
<definition of working storage (i.e., read-write 

memory )> 
FREEZE 
EIH) 

P2 IDEIJT 

BSS :LC:-:ZERO: 

<read-only code> 
END 
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PI IDEN3? 

BSS :LC:-:ZERO: 
<read-only code> 
END 

The FREEZE directive at the end of KL preserves all the 
definitions in this package so they can be referenced in packages 
P2 axnd P3. By including the definitions of all the working storage 
cells in the preserved definitions, these symbols need not be 
declared as external. Also, it makes "external" arithmetic on these 
symbols possible in V2 and P3j and it reduces the number of 
imdefined symbols printed at the end of an assembly. Packages 
P2 and P3 start with the rather peculiar looking B^S in order 
to set the location counter so that references between the 
packages will be correct. This is the main pur-oose of :LC:, 
it saves the final value of the location counter from the 
previous package for use by the current package. In order for 
this scheme to work, all three packages must be loaded at the 
same location, usually for large re-entrant programs. 

Assume ALPHA is a symbol defined in PI. Unless some 
special action is taken, ALEHIA will be output to DOT three times, 
once at the end of PI, once at the end of P2, and once at the end 
of P3. To avoid this, all symbol and opcode definitions are 
marked after they have been output once so that they won*t be 
output again. 
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k.lSi FRGT Do not output a specific symbol 

FRGT si,S2,... [comment] 

The symbols s^ (which must have been previously defined) 
are not output to DHP. FRGT is especially useful in situations 
vhere symbols have been used im macro expansions or conditional 
assemblies, and have meaning only at assembly time. When DDT 
is later used, memory locations are sometimes printed out in 
terms of these meaningless symbols. It is desirable to be able 
to keep these symbols fj:om being delivered to DDT, hence the 
FRGT directive. 



4-15a 



4.125 FRGTOP Por-get selected opcodes 
FRGTOP s^,s , ... [comment] 

The s. must be opcodes. The specified opcodes are marked 
as forgotten and will not be output to DDT. Since DDT knows 
in advance about the standard instruction set (e.g., LDA, BRS, 
CIO), FRGTOP or such opcodes has no effect. It follows that 
the chief use of FRGTOP will be to suppress output of opcodes 
generated by OPD and POPD. 

FRGTOP does not take a label. 
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4.128 GLOBAL Reverse external specification 
GLOBAL [comment] 

Causes all symbols which would normally not be external to be ex- 
ternal and all symbols which would be external not to be external. 
This directive remains in effect until an END or LOCAL directive is 
encountered at which time the normal external determination method 
is used. For example. 





GLOBAL 




START 


LDA 


= 1 


A 


EXT 


B 


$c 


STB 


X 



would cause START to be external and A and C not to be external. 



4-17 



U.13 IDEUT Identification of a package 

symbol IDEM* [comment] 

The symbol in the label field is delivered to DDT as a 
special identification record. DDT uses the IDENT name in con- 
junction with its treatment of local syiAbols: in the event of 
a name conflict between local symbols in two different subprograms, 
DDT resolves the ambiguity by allovring the user to concatenate 
the preceding IDENT name with the symbol in question. Also, 
during an assembly the first six characters of the symbol followed 
by the word * IDENT' are typed on the teletype to show the user 
what package is being assembled. The progress of an assembly- 
can be followed by placing IDENT' s at various points in the 
package . 
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4. 14 LIST Set listing controls 

4.143 LOCAL Restore normal external meaning; 
LOCAL [comment] 

Restores normal external determination method. (See GLOBAL directive.) 



i+.15 NQLIST Reset listing controls 



■KrrtT TOm l'' ■*" 



NOLIST 



[ comment ] ] 



There are various booleans which control the format in 
which statements are listed (certain fields and/or certain 
kinds of statements may be suppressed, or listed selectively) . 
The user is aJ-lowed to set (or reset) these booleans via the 
LIST (or NOLIST) command. Each of the S. may be one of the 
following special symbols: 
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s. Set (or 

1 


reset) 


What is (or is not) listed 


LCT 




the current value of the location 
counter, in octal 


SLCT 




the symbolic address of the current 
value of the location counter 


VAL 




the value of the statement, if it is 
one of the directives: EQU, NCHR, 
KARG, IF, ELSF. (in octal) 


SRC 




the symbolic source code 


COM 




the comment field of a statement, a 
comment statement 


CAT.T, 




macro and RPT calls 


• DEF 




MACRO and RPT definitions 


EXP 




macro and RPT expansions 


SKIF 




the skipped parts of gin IF statement 


EXT 




external symbol references (at the 
end of the assembly 
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In addition, s. may be "ALL", which will cause all of the 
booleans in the table to be set (or reset). 

If a LIST (or NOLIST) directive is encountered for which 
no arguments (s.) have been specified, NARP will begin (or 
cease) listing statements on the LISTING FILE (the teletype, 
in case no other listing file is specified when the assembly 
is begun) according to the current settings of the listing 
booleans. Including "GO" among the arguments for a LIST 
(or NOLIST) will have the same effect. 

When NARP is called, the listing booleans are initialized 
as follows; 

Set: LCT, VAL, SRC, CbM, CALL, DEF, EXP, EXT 
RESET: SLCT, SKIP 

and NARP is in its "no list" state, i.e., listing will not 

be started unless (and until) the program initiates it with a 

LIST directive. 

Examples of the LIST directive: 

NOLlST ALL Resets all format booleans 

LIST SRC, GO Sets SRC boolean and starts listing. 

(only the source code will be listed) 

Examples of listing format: 

CCM^ 



(SET A) 



LCT 


SLCT VAL 




SRC 




' 


c ""f^ 


• r 






00117 


(A) 3 


A 


EQU 


6/2 


00117 


(HERE) 


HERE 


LDA 


A*B,2 


00120 


(HERE+1) 




CLB 
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k.l6 OCT Interpret integers as octal 

OCT [comment] 

The radix for integers is set to eight so that all following 
integers (except those with a D- suffix) axe interpreted as octal. 
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^.17 OPD Define an o-pcode 
symbol OPD value [, class [, shift kludge]] 

The symbol in the label field is defined as an opcode with 
a value equal to the first expression in the operand field. All 
expressions in the operajid field must be defined and absolute; if 
an optional expression does not appear then the value is assumed, 
value : computed mod 2 (see important note below) 
class : must have a value of 0,1, or 2: 

- the opcode may or may not have 

an operand 

1 - the opcode does not take an 

operand 

2 - the opcode requires an operand 

shift kludge: must have a value of or 1: 

- non-shif^ instruction 

(see section 3) 

1 - shift instruction (see section 3) 

Note: Although an opcode that takes operands can be defined with 
bits blOb23 set, the u-^er must be careful of what he is do inc. 
In particular, if such aji opcode a-Dp<^ars in an instruction which 
contains a literal or an undefined value then bits blO-b23 of the 
opcode are set to zero. 

If the symbol in the label field is already defined as an 
o-ncode then the old definition is lost. 
Examples : 

Q55B5,2 

Oi|600001B,l 

020B5 



ADD 


OPD 


CLA 


OPD 


ROY 


OPD 


NOP 


OPD 
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4.l8 PAGE Begin a new page on the listing 

PAGE Lexpression [comment]] 

This directive causes page e^'ects on the assembly listing 
mediiiin. The niamber of ejects is determined by the expression in 
the operand field (which must be defined and absolute). If 
there is no operand then one eject is assumed. If a page eject 
has Just occixrred then one less than the specified number of 
ejects is made. 
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U.19 POPD Define a programmed operator 

symbol POPD value [,c las s[, shift kludge]] 

This directive does exactly what OPD does with one addition: 
The instruction BRU* is placed in the memory location whose 
address is in b2-.b8 of the value given to the symbol (this 
address must be in the range [106^, 177B]). Thus 



MIN 


POPD 


10015,2 




114 IN 


SKG* 





THE CALL 'MIN ALPHA' WILL 




BRR 





CAUSE THE MINiriUM OF 




T,nA* 





A-REG AND ALFHA TO BE 




BRR 





LEFT IN A-REG. 



will cause BRU LMIN to he loaded in word lOOB. 
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^+.20 RELORG Assemble relative with absolute orig;in 
RELORG expression [comment] 

On occasion it is desirable to assemble in the midst of 
otherwise normal program a batch of code which, although loaded 
in ocre in one position, is destined to run from another position 
im memory, (it will first be moved there in a block.) This is 
particularly useful when preparing program overlays. The 
expression in the ODerand field (which must be absolute and 
defined) denotes an origin in memory. The follovring occurs v/hen 
the directive is encountered: 

a.) The current value of the location counter is saved, and 

im its place is put the absolute origin (i.e., the 

va3.ue of the expression). This fact is not revealed 

to DET, however, so during loading the next instruction 

assembled vfill be placed in the next memory cell available 

as if nothing had happened. 
b.) The mode of assembly is switched to absolute, i.e., all 

symbols defined in terms of the location counter will 

be absolute. 
It is possible to restore normal relocatable assembly (see section 
4.22). 

As an example of the use of RELORG, consider a program 
beginning with RELORG 300B, The assembler's output represents 
an absolute -Drograjn whose origin is OO30O0, but which can be 
loaded anyv/here using DOT in the usual fashion. Of course, 
before executing the prograjn it will be necessary to move it to 
location OOSOOg. 

As another example, consider the follwiing use of RELORG and 
RETREL: 

<normal relocatable program> 

RELORG lOCB 

<ab solute program with origin at 100B> 

RELORG 200B 

<ab solute program with origin at 200B> 
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REIREL 

<normal relocatable pro^o:ani> 

KEI/ORG 30(B 

<a"hsolute program with origin at 30C(B> 

END 
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If. 21 REM Type out remark 

REM text 

This directiye causes the text in its operand and comment 
fields to be typed out either on the teletype or whatever file 
has been designated as the text file (see section 6.2). This 
typeout occurs regardless of what listing controls are set. The 
directive may be used for a variety of purposes: It may inform 
the user of the jirogress of assembly; it may give him instructions 
on what to do next (this might be especially nice for complicated 
assemblies); it might announce the last date the source language 
was updated; or ±t might be used within complex macros to 
sho;^ which argument substrings have been created during 
expansion of a highly nested macro (for debugging purposes). 



4-28 



It. 22 RETREL Return' to relocatable assembly 

RETREL [comment] 

This directive is used when it is desired to return to 
relocatable assembly after having done a RELORG. It is not 
necessary to use RETREL unless one desires more relocatable 
program. An example of the use of RETREL is shown in section 
1^.20. The effects of RETREL are 

a.) to restore the location counter to the value it would 

have had if the RELORG (s) had never appeared, and 
b.) to return the assembly to relocatable mode so that 
labels are no longer absolute. 
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k.23 TEXT Generate text jk character per word ) 

[[$] label] TEXT string [comment] 

This directive is exactly the same as ASC (see section k,l) 
except that characters are taken as six bits each and are stored 
four to a word. 
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^.0 Conditional assemblies and macros 

5.1 IF, ELSF, ELSE, and EKDF If statements 

It is frequently desirable to permit the assembler either to 
assemble or to skip blocks of statements, depending on the value of 
an expression at assembly time. This is primarily what is meant 
by conditional assembly . In NAi^P, conditional assembly is done 
by using either an if ' statement or a repeat statement . 

The format of an if statement is 

IF expression [comment] 

< if body > 

ENDF (comment) 

The if body is any block of NARP statements, in particular, it may 
contain directives of the form 

ELSF expression [comnent] 
8ind 

ELSE [comment] 

If the operand of IF is true, then the block of code up to the 
matching ENDF (or ELSF or ELSE) is processed; otherwise, it is 
skipped. The values for true and false are: 

true : value of expression > 
false : value of expression < 



Examples: 






IF 


1>0 




U)A 


ALPHA 


> 


STA 


BETA 


ENDF 






IF 







LDA 


GAMMA 


1 


STA 


DELTA 


ENDF 







processed 



skipped 
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Often there are more than two alternatives, so the ELSF 
directive is used in the if body. When ELSF is encountered while 
skipping a block of statements, its operand is evaluated (just 
as for if) to decide whether to process the block following the 
ELSF. 



Examples : 






IF 


0> 1 




LDA 


ALPHA 


skipped 


ELSF 


1 > 




LDA 


BETA 


processed 


ENDF 






IF 


0> 1 




LDA 


ALPHA 


skipped 


ELSF 


> 1 




T.m 


BETA 


skipped 


ErJDF 






IF 


1 > 




LDA 


ALPHA 


processed 


ELSF 


1> 




LDA 


BETA 


skipped 


ENDF 






IF 


0> 1 




LDA 


ALPFIA 


skipped 


ELSF 


1> 




LDA 


BETA 


processed 


ELSF 


1> 




LDA 


GAMJ^IA 


skipped 


ENDF 







From the last two examples above it should be clear that either 
no blocks are processed or precisely one is; thus, as soon as one 
block is processed, all following blocks are skipped regardless 
of whether the ELSF expressions are true. 



IF 


0> 1 


LDA 


ALPHA 


ELSE 




LDA 


BETA 


ENDF 
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An ELSE directive is equivalent to an ELSE directive with a 
true expression. 
Exeimple : 



skipped 
processed 



As a more general example, consider the following: 

IF el 

< body 1 > 
ELSE e2 

< body 2 > 
ELSF e3 

< body 3 > 
ELSE 

< body h > 
ENDF 

There are four possibilities: 

a) el > : process body 1, skip the other three 

b) el < 0, e2 > : process body 2, skip the other three 

c) el < 0, e2 < 0, 

e3 > : process body 3> skip the other three 

d) el < 0, e2 < 0, 

e3 < : process body k, skip the other three 

The bodies between the IF, ELSF, ELSE, and ENDF directives 
may contain arbitrary NARP statements, in particular they may 
contain other if statements. This nesting of if statements may 
go to any level. 

When evaluating the expression in the operand field of IF or 
ELSF, all undefined symbols are treated as if they were defined with 
value -1. These expressions must be absolute. 



5-2 KPT, CRPT. and ENDR Repeat statements 

A repeat statement is a means of processing the same text many 
times. The format is 

[ [$ ] label] EPT expression[ , increment list ] [ comment 1 
< repeat body > 
Emm [comment] 

The value of the RPT operand (which must be defined and absolute) 

determines how many times the repeat body will be processed, while 

the increment list (described below) is a mechanism to allow the 

values of various symbols to be changed each time the repeat body 

is processed. 

Example : 

ABC RPT k 
DATA 
ENDR 

This is equivalent to 
ABC 



DATA 





DATA 





DATA 





DATA 






An increment list has the form (s=el[^e2] ). . . (s=el[ ,e2]) 
where s stands for a symbol and el and e2 denote expressions 
(which must be absolute; undefined syiabols are treated as if they 
were defined with the value -l). Before the repeat body is processed 
for the first time, each symbol in the list is given the value of 
its associated el. Thereafter, each symbol is incremented by the 
value of its associated e2 Just before the repeat body is processed. 
If e2 is missing, the value 1 is assumed. There is no limit on 
the number of elements that may appear in an increment list. 
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Example: 

RFC 3,(l=4)(j=o,-l) 

DATA I 

DATA J*I+1 
ENDR 

This resiilts in code equivalent to the following: 



DATA 


If 




DATA 


0»^lf+l 


=1 


DATA 


5 




DATA 


-1^+1 


=:~If 


DATA 


6 




DATA 


-2*6+1 


=-11 



There is another format for RPT: 
[[$llabel] RPT (s=el[,e2],e3)[ increment list] [comment] 
In this case, the number of times the repeat body is processed is 
determined by the construct (s=el[ ,e2],e3). This is the same as 
an increment list except that it includes a third expression 
(which must be absolute; all undefined symbols are treated as if 
they were defined with the value -l), namely a bound on the value 
of the symbol. As soon as the bound is passed, processing of the 
repeat body stops. In the example above, the same effect could 
have been achieved by writing the head of the repeat statement as 

RPT (j=0,-l,-.2Xl=if) 
or as 

RPT (I=U,6XJ=0,-1) 

Note that the bound does not have to be positive or greater than 
the initial value of the symbol being incremented; the algorithm 
for determining when the bound has been passed is given below. 

Occasionally one wishes to perform an indefinite number of 
repeats, terminating on an obscure condition determined in the 
course of the repeat operation. The conditional repeat directive, 
CRPT, serves this function. Its effect is like that of RPT (and 
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its repeat body is also closed off with an ENDR) except that instead 
of giving a number of repeats, its associated expression is evaluated 
just prior to each processing of the repeat body to determine 
whether to process the block. As for IF, > means true, < means 
false; the expression must be defined and absolute each time it is 
evaluated. The form is 

[[$] label] CRPT expression [, increment list] [comment] 

For example, one may write 

CRPT X>Y 
or 

CRPT STOP,(X=l,2)(Y=-3) 

Note that the statement 

CRPT 10 

will cause an infinite number of repeats. 

The following flowcharts describe precisely the actions of 
the various repeat options: 

RPT expression[, increment list] 



skip the whole 
repeat block 




top 




count : r: value of expression 



yes 




no 



initialize symbols in increment 
list; evaluate all e2 expressions 



process the repeat body ^ 



3 f 



increment the symbols in 
the increment list 



country; count -1 



yes 




Xl^unt = 0\. 



no 



The el and e2 expressions 
are evaluated just once. 



stop^ 
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yes 



^tOpL 



RPT (S=el[,e2],e3)[ increment list] 



VbarV 



8:- el 



::k- 



evaluate e2 and e3; 
initialize symbols in 
increment list; evaliiate 
all e2 expressions. 




< 



All expressions are 
evaluated just once 



(S>e3)^sign( e2)>03 ^ 







process the repeat block 



AL 



increment the symbols in 
the increment list 

8:= S+e2 
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CRPT 



express ion [, increment list] 



.start 




initialize symbols in increment 
list; evaluate all e2 expressions; 



jJL 



evaluate expression 



no 





3^ 



M , 



value expression > 




yes 



process the repeat block 



increment the symbols in the increment 
list 



All el and e2 expressions 
are evaluated just once 



This expression is eval- 
uated over and over again 
and, of course, the values 
of the symbols in this 
expression may change from 
one evaluation to the next. 



The contents of a rei>eat body may contain any MRP code, in 
particular it may contain other repeat statements; the nesting 
repeat statements may go to eoiy level. 



of 
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5.3 Introduction to macros 

On the simplest level a macro name may be thought of as an 
abbreviation or shorthand notation for one or more assenbly 
language statements. In this respect it is like an opcode in that 
an opcode is the name of a machine command and a macro name is 
the name of a sequence of assembly language statements. 

The 9U0 has an instruction for skipping if the contents of 
a specified location are negative, but there is no instruction 
for skipping if the accumulator is negative. The instruction 
SKA (skip if memory and the accumulator do not compare ones) will 
serve when used with a cell whose contents mask off all but the sign 
bit. The meaning of SKA when used with such an operand is "skip 
if A is positive" . Thus a programmer writes 

SKA ^ksrj 

BRU NEGCAS NEGATIVE CASE 

However, it is more than likely the case that the programmer 

wants to skip if the accumulator is negative. Then he must write 

SKA =i|B7 

BRU *+2 

BRU POSCAS POSITIVE CASE 

Both of these situations are avrkvjard in terms of assembly 3-«nguage 
programming . 

But we have in effect just developed simple conventions for 
doing the operations SKAP and SKAN (skip if accumulator positive 
or negative). Define these operations as macros: 

$KAP MACRO 

SKA =J*B7 
ENDM 



SKAN MACRO 

SKA ^B7 
BRU *+2 

ENIM 



Now, more in keeping with the operations he had in mind, the 
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Programmer may write 

A22 SKAN 

BRU POSCAS 

The advantages of being able to use SKA? and SKAN should be 
apparent. The amount of code written in the course of a program 
is reduced; this in itself tends to reduce errors. A greater 
advantage is that SKA? and SKAN are more indicative of the action 
that the programmer had in mind, so that programs written in this 
way tend to bfi easier to read. Note, incidentally, that a label 
may be used in conjunction with a macro. Labels used in this way 
are usually treated like labels on instructions; they are assigned 
the current value of the location counter. This will be ditcussed 
in more detail later. 

Before discussing more cornplicated uses of macros, some 
additional vocabulary should be established. A macro is an 
arbitrary sequence of assembly language statements together 
with a symbolic name . During assembly, the macro is stored in an 
area of memory called the string storage . Macros are created 
(or, as is more frequently said, defined ) by giving a name and the 
associated sequence of statements. ITie name and the beginning 
of the sequence of statements are designated by the MACRO directive 
name MACRO 



ENDM 
The end of the sequence of statements is indicated by the EmJM 
directive . 

Refer to figure 1. When the assembler encounters a MACRO 
directive, switch B is thrown to position 1 so that the macro 
is simply copied into the string storage; note that the assembler 
does no normal processing but simply copies the source language. 
When the ENI^l terminating the macro definition is encountered, 
switch B is put back to position and the assembler goes on 
processing as usual. 

It is possible that within a macro definition other definitions 
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Figure 1: Information Flow During Macro Processing 



SOURCE 
LANGUAGE 



BINARY 

MACHINE 

LANGUAGE 



"^~ 



ASSEMBLER 

TPi 



5 








O 1 



^ 



STRING 
STORAGE 



A B 



1 

1 
1 1 



Effect 

normal assembly 
macro definition 
macro expansion 
macro definition during 
macro expansion 
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may be embedded. The macro defining machinery counts the 
occurrences of the MACRO directive and matches them against the 
occurrences of ENDM. Thus switch B is actually placed back in 
position only when the ENDM matching the first M/\CEO is 
encountered. Therefore, MACRO and ENDM are opening and closing 
brackets around a segment of source language. Structures like 
the following are possible: 



name 1 


MACRO 1 


name 2 


MACRO 1 




name 3 


MACRO -T 
ENI»1— ' 




name k 


MACRO-n 
ENDM-- 
ENDM 




name 5 


MACRO H 
ENDM—' 

T?TvTnT.f ... > 



The utility of this structure will not be discussed here. Use 
of this feature of imbedded definitions should in fact be kept 
to a minimum since the implementation of this assembler is such 
that it uses large amounts of string storage in this case. What 
is important, hovrever, is an understanding of when the various 
macros are defined. In particular, when name 1 is being defined, 
name 2, 3> etc., are not defined; they are merely copied into 
string storage. Name2, for example, will not be defined until 
namel is expanded. (it should be noted that macros, like 
opcodes, may be redefined.) 

The use of a macro name in the opcode field of a statement 
is referred to as a call . The assembler, upon encountering a macro 
call, moves switch A to position 1 (see figure l). Input to the 
assembler from the original source file temporarily stops and comes 
Instead from string storage. During this period the macro is said 
to be undergoing expansion. It is clear that a macro must be 
defined before it is called. 

An expanding macro may include other macro calls, and these, 
in turn, may call still others. In fact, macros may even call 
themselves; this is called recursion . Examples of the recursive 
use of macros are given later. When a new macro expansion begins 
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within a macro expansion, information about the progress of 

the current expansion is saved. Successive macro calls cause 

similar information to be saved. At the end of each expansion 

the information about each previous expansion is restored. When 

the final expansion terminates, switch A is placed back in 

position 0, and input is again taken from the source file. 
V 
Now let us carry our example one step further. One might 

argue that the action of skipping is itself awkward. It might 

be preferable to write macros BRAP and BE^N (branch to specified 

location if contents of accumulator are positive or negative). 

How is one to do this? The location to which the branch should 

go is not known when the macro is defined, in fact, different 

locations will be used from call to call. The macro processor, 

therefore, must enable the programmer to provide some of the 

information for the macro expansion at call time . This is done 

by permitting dummy arguments in macro definitions to be replaced 

by arguments (i.e., arbitrary substrings) supplied at call time. 

Each dummy argument is referred to in the macro definition by a 

subscripted symbol. This symbol or dummy name is given in the 

operand field of the MACRO directive. 

Let us define the macro BRAP: 

BRAP MACRO LABEL 
SKAN 
BRU LABEL(l) 

Emu 

When called by the statement 'bRAP POSCAS*, the macro will 

expand to 

SKA =l^B7 
BRU *+2 
BRU POSCAS 

Note that BRAP was defined in terras of another macro, SKAN. Also 
note that as defined BRAP was intended to take only one argument; 
other macros may use more than one argument. 



5-lU 



The macro CBE (compare and branch if equal) takes two 
argiaments. The first argument is the location of -a cell to be 
compared for equality with the accumulator; the second is a 
branch location in case of equality. The definition is 
CBE 



MACRO 


D 


SKE 


D(l) 


BRU 


♦+2 


BRU 


D(2) 


ENDM 





When CBE is called by the statement 
CBE -21B,EQL0C 
the statements generated will be 



SKE 


=21B 


BRU 


*+2 


BRU 


EQLOC 



Note that in the macro call, the arguments are separated by 
commas . 

The following sections describe macro definitions and 
calls in more detail. 
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5. if MACRO, IMACRO, and ENDM Macro definition 



The form of a macro definition is: 

[dijmmy[, generated, expression] [comment] 



r MACRO 
name i or 

LlMACROj 



vhere name , generated , and dummy are all symbols, and expression 
is an expression. 

lilACRO is completely equivalent to MACRO except that if 
name is defined as a macro with MACRO the construct 

label name arguments 

will automatically cause "label" to be defined as the current 
value of the location counter, whereas if name were defined 
with LMACRO this automatic definition of "label" would not 
occur. 

Some details of the definition 

^^ ggng^a-ted appears, it should not be the same symbol 
as dummy , and neither of them should be "^MACRO", "IMCRO", or 
"ENDM. " 

If name is already defined as an opcode, the old definition 
is completely replaced by the new. 

If the MACRO (or IM.CRO) directive has no operand, then 
name is defined as an opcode that taJtes no operands. Otherwise, 
name becomes an opcode that may or may not take a.n operand. 

Whole- line comments (lines beginning with ^) in the macro 
body are not saved in string storage as part of the macro 
definition, but comments following instructions are. Thus, it 
behooves the programmer to avoid the latter, as they eat up 
string storage. 
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When a macro body is placed in string storage, superfluous 
blanks are removed. Thus, any contiguous string of blanks is 
compressed to one blank with the following exceptions: 

a) Blanks enclosed in single quotes (*) are not compressed. 

b) Blanks enclosed in double quotes (") are not compressed. 

c) Blanks enclosed in parentheses are not compressed. In 
this use, the nesting of parentheses is taken into 
account, but a parenthesis between single or double 
quotes is not considered as part of the nesting 
structure. 

In most cases the programmer need not worry about these 
conventions, although there are times when he may get pinched. 
For example, if 

ASC ^x^iBfo 
appears in a macro definition, it will be expanded as 

ASC ihM 
To avoid such problems use 

ASC 'A^iiB' 
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5.U.1 Dummy arguments 

The dummy eurgument specified as an operand of the MACRO 
directive may appear anywhere in the macro body, followed by a 
subscr^ipt. At call time the subscript is evaluated and its value 
is used to select the appropriate argument supplied in the call. 
Before describing the various kinds of dummy arguments a few 
conventions are needed: 

a) In the following, "argument" will refer to the character 
string as given in the macro call after possible enclosing 
parentheses have been removed (see section 5.6 for the 
format of argument strings). 

b) The number of arguments supplied by the call is n {n>0). 

c) The number of characters in argument ei is n{ei). 

d) The structure ei for i an integer stands for an expression. 
(However, its value stands for some argument usually, so 
ei will be used somewhat ambiguously to stand for an 
escpression or the value of an expression.) The first 
argument in a call is numbered 1. 

e) The dummy argument is assumed to be "D". 

With the above in mind, we consider the three forms of dummy 
arguments: 

1) D(el) 

This expands to argument el (which may be the null string), where 
< el < n. (if el = then D(el) expands to the label field of 
the macro call; see section 5*6.) 
Special notation: D() = D(i) 

2) D(el,e2) 

If el > e2 then this expands to the null string (range of values 
of el and e2 is arbitrary), otherwise, this expands to argument 
el through e2, where < el < e2 < n, with each argument enclosed 
in parentheses and a comma inserted between each argument. For 
example, D(3,3) = (b(3)). 
Special notation: D(,) = D(l,n) 

D(,el) = D(l,el) 

D(el, ) = D(el,n) 
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3) D(el$e2,e3) 
Li all cases^ ^ £ ®^ £ "^ ™^^^ ^® true. If e2 > e3 then this 
expands to the null string (range of values of e2 and e3 is 
arbitrary), otherwise, it expands to characters e2 through e3 
of argument el, counting the first character of an axgiiment as 
character 1, If either e2 or e3 lies outside the argument, then 
the nearest boundary is chosen. To be more precise, before using 
e2 and e3 to select the piece of argument el that is desired, the 
following transformation is made: 

e2:= max (l>,e2); e3:«= max (l,e3); 

e2:= min (n(el), e2); e3:= min (n(el),e3); 

If argtiment el is the null string, then the dummy argument expands 
to the null string regardless of the values of e2 and e3. 
l^ecial notations : 

D(el$,) = D(e4l, n(el)) = D(el) 

D(el$,e2) = D(el.tl,e2) 

D(el$e2,) = D(el$e2,n(el)) 

D(el$e2) = D(el$e2,e2) 

D(el$) = D(el$l) = D(el$l,l) 

In any of the six forms mentioned above, el may be missing; 

if so, 1 is assumed. E.g., D{$) = D(1$1,1). 
A general rule which will help in remembering what the special 
notations mean is the following: "Whenever an expression is 
missing from a form, the value 1 is assumed unless the expression 
is missing from a place where an upper bound is expected (as in 
D(3, ) or d(3$2, ), in which case the largest 'reasonable* value is 
assumed." 

In any of the above three cases, if an expression which 
designates an argument is out of range, then an error message is 
typed and argument is taken. 
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Following is an example of the various forms of dummy 
arguments : 



Macro definition: 



MACRO 

I)(2) 

ASC 

TEIXT 

ASC 

ASC 

ENDM 



D() D(0) 

*D(lf.)» D(-3,-^) 

•D(l$3,if)' 

•D(2$-3,l8)' 



NULL STRING 



Macro call: 
BETA 



XAMPLE ALPHA,ADD,GAMMA,DELTA 



Macro expansion: 



KEtA 



ADD 


ALPHA BETA 


ASC 


* (GAMMA), (DELTA)' 


TJ!;XT 


•(DELTA)' NULL STRING 


ASC 


•PH' 


ASC 


'ADD' 
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5.^.2 Generated symbols 

A macro should not, of course, have in its definition an 
instruction having a label. Successive calls of the macro would 
produce a multiply-defined symbol. Sometimes, however, it is 
convenient to put a label on an instruction within a macro. 
There are at least two ways of doing this. The first involves 
transmitting the label as a macro argument when it is called. 
This is most reasonable in many cases; it is in fact often 
desirable so that the programmer can control the label being 
defined and can refer to it elsewhere in the program. 

However, situations do arise in which the label is used 
purely for reasons local to the macro and will not be referred 
to elsewhere. In cases like this it is desirable to allow for 
the automatic creation of labels so that the programmer is freed 
from worrying about this task. This may be done by means of the 
generated symbol . 

A generated symbol name may be declared when a macro is 
defined, specifying the name and the maximum number of generated 
symbols vfhich will be encountered during an expansion. These 
two items follow the dummy symbol name given in the MACRO directive 
(as shown in section ^ .h above) if the programmer wishes to use 
generated symbols in a macro. For example, 
MUMBLE MACRO D,G,4 
< macro body > 
ENDM 
might contain references to G(i), G(2), G(3), and G(U), these 
being individual generated symbols. 

With regard to generated symbols the macro expansion machinery 
operates in the following fashion: A generated symbol base value 
for each macro is initialized to zero at the beginning of assembly. 
As each generated symbol is encountered, the expression constituting 
its subscript is evaluated. This value is added to the base 
value, and the sum is produced as a string of digits concatenated 
to the generated symbol name ; the first digit is always O to 
reduce the likelihood of the generated symbol being identical to 
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a normal symbol defined elsewhere by the programmer. Thus, the 
first time MUMBLE is called, G(2) will be expanded as G02, G{k) 
as G^, etc. 

At "the end of a macro expansion, the generated symbol base 
value is incremented by the amount designated by the expression 
following the generated symbol name in the MACRO directive. This 
is k in the case of MUMBLE. Thus, the second call of MUMBLE will 
produce in place of G(2), G^, the third call will produce G010, 
etc. It should be clear that the generated symbol name should 
be kept as short as possible. 

The expression in the macro head (call it m) must have a 
value in the range [ 1,1023]. A generated symbol subscript must 
have a value in the range [l,ml. 
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5«^«3 Concatenation 

Occasionally, it is desirable to have a dianmy argument follow 
immediately after an alphanumeric character, for example, to 
have D(1) follow just after ALPHA. But then the assembler 
would not recognize the dummy because it would see ALPElAD(l) 
instead of d(i). To get around this problem the concatenation 
symbol ' .St* is introduced. Its sole purpose is to separate a 
dummy argument (or conceivably a generated symbol) from a preceding 
alphanumeric character during macro definition. Thus, the example 
becomes ALPHA. &D(i). The concatenation symbol is not stored in 
string storage so it does not appear during expansion. 

As an exan^le, say that we wish to define a macro STORE, 
and suppose we have established the convention that certain 
temporary storage cells begin with the letters A, B, or X 
depending on what register is saved there. The definition is: 

STORE MACRO D 

ST.&D($) D(1) 

If called by the statements 

STORE B17 
STORE Xkh 

the macro will expand as 

STB B17 
STX Xkh 

The concatenation symbol may appear anywhere in a macro 
definition, but it is only necessary in the case described above. 
If one macro is defined within another, any concatenation symbols 
within the inner macro i>rill not be removed during the definition 
of the enclosing macro. 
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^.h.k Conversion of a value to a digit string 

As an adjunct to the automatic generation of symbols (or 

for any other purposes for which it may be suited) a capability 

is provided in the assembler's macro expansion machinery'' for 

conversion of the value of an expression at call time to a 

string of decimal digits. The construct 
(^expression) 

will be replaced by a string of digits equal to the vallue of 

the exjjression. For example, if X=5 then 
AB($2^«X+l) 

will be transformed into 
ABll 

If the value of the expression is zero then the digit string is 

*0'; if it is negative then the digit string is preceded by a 

minus sign. 

This conv^^rsion scheme can also be used inside repeat blocks; 

for example 

RPT (1=1,10) 
TEMP($I) BSS 1 
ENDR 

creates 10 cells labelled TEMPI through TEMPIO. 
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5.^.5 A note on subscripts 



The expressions used as subscripts for dummy arguments 
and generated symbols, as well as the expressions used in the 
conversion to a digit string must be absolute. Any undefined 
syinbols appearing in these expressions are treated as if they 
were defined with the value -1. These expressions may themselves 
contain dummy arguments, generated symbols, and ($...), so 
constructs like ($4+D(I*D(3))) are possible. 
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5.5 NARG and NCHR Number of arp^uments and number of characters 

Macros are more useful if the number of arguments supplied 
at call time is not fixed. The precise meajiing of a macro (and 
indeed, the result of its expansion) may depend on the number or 
currangement of its arguments. In order to permit this, the 
macro undergoing expansion must be able to determine at call time 
the numbfer of arguments supplied. The NARG directive makes this 
possible. 

NARG functions like EQU except that no expression is used 
with it. Its form is 

[ $3 symbol NARG [comment] 
The function of the directive is to equate the value of the symbol 
to the number of arguments supplied to the macro currently 
undergoing expansion. The symbol can then be used by itself or 
in expressions for any purpose, NARG may appear in any macro, 
even one which has no dummy argument (and thus never has any 
arguments at call time); it is an error for NARG to appear outside 
a macro. 

It is also useful to be able to determine at caU. time the 

number of characters in an argument. NCHR functions by equating 

the symbol in its label field to the nujnber of cheiracters in its 

operand field. Its form is 

[$] symbol NCHR [character string [comment]] 

where "character string" has exactly the same form as an argument 

supplied for a macro call, i.e., if it involves blanks, commas, 

or semi- colons it should be enclosed in parentheses (see section 

5-6), NCHR can appear anyv^here, both inside and outside macros, 

but it is most useful in macros for determinine the length of 

arguments. 

Examples : 

A NCHR ABCDPT A: =6 

B NCHR (,,XYZ,,) B:=7 

C NCHR D(I) C:=? 
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5-6 Macro calls 

The format of a macro call is : 

([$) label) macroname [argstring] [comment] 

Such a call causes the macro ^ose name apx>ears in the 
opcode field to be expanded, with the dummy arguments in the 
macro body replaced by the actual arguments of the argstring. 

The label field is always transmitted as argument 0, so 
that D(el), where el has value 0, is always legal inside a macro. 
An occurrence of D (el), where el=0, will be replaced by the 
label field. If the label field is empty, then D(el) expands 
to the null string. At most seven characters will be transmitted 
this way: the first six characters of the symbol in the label 
field, preceded by *$* if the label field begins with *$*. 

If the user wishes to transmit an argument to a macro in 
the label field of the macro call, but does not wish to have 
the symbol in this field defined, he should define the macro 
with DdACRO rather than MACRO. (See section ^ .h) An example: 



D 

D(l) 

D(2) 

-D(l) 



k,kB7 



kwr 

Notice that this would have caused a doubly- defined symbol 
error had MACRO been used rather than IMACRO. 





NT 


LMACRO 
RPT 
DATA 
ENDR 




D(0) 


. DATA 

Mm 


when called by: 








DTE 


NT 


expands as: 




DATA 
DATA 
DATA 
DATA 




DTE 


DATA 
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A macro call may or may not have an arg string (see section 
5 A). If an arg string is present, it may contain any niomber 
of arguments, in fact, more than are referred to "by the macro. 

Before describing an arg string, the following should be 
noted: blanks, commas, semi-colons, and parentheses that are 
enclosed in single or double quotes are treated exactly like 
ordinary characters enclosed in quotes; they do not serve as 
terminators, separators, delimiters, or the like. In effect, 
when the argument collector in NARP is collecting arguments 
for a macro call, the occurrence of a quote causes it to stop 
looking for special characters except for a matching quote (and, 
of course, carriage return, which is an absolute terminator). 
A single quote enclosed in double quotes is not a special 
character and vice versa. Thus, when a blank, comma, semi-colon, 
or parenthesis is referred to in the following, it is under- 
stood that it is not enclosed in quotes. 

An arg string for a macro call has the following format: 

<argp>,<arg>, . . . ,<arg> <terminator> 

where a terminator is a blank, semi-colon, or carriage return. 
There are three forms of <ar^: 

1. <ar^ may be the null string, 

2. If the first character of <arg> is not a left paren- 
thesis then <arg> is a string of characters not con- 
taining blank, comma, semi-colon, or carriage return 
(remember that blanks, commas, and semi-colons may 
appear in <arg> if they are enclosed in quotes). 

3. If the first character of <arg> i£ a left parenthesis 
the <arg> does not terminate until a blanlc, comma, 

or semi-colon is encountered after the right parenthesis 
which matches the initial left parenthesis ("matches" 
means that all left and right parentheses in the 
argument are noted and paired off with each other so 
that a nested parentheses structure is jjossible). 
Of course, a carriage return at any point immediately 
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terminates <arg>. Again, remember that blanks, commas, 
serai-colons, and parentheses enclosed in quotes are 
ignored when <ar^ is being delimited. The initial 
left parenthesis and its matching right parenthesis 
(which need not be the last character in <arg>) are 
removed before <arg> is transmitted to the macro. 
Examples : 

AMAC (>z.;a^ ),, •H0USE,^R0GER', (AB")") 

D(2) = null string 
D(3) = *HOUSE,^ROGER» 
D(U) = AB")" 

5 •? Examples of conditional assembly and macros 

1. It is desired to have a pair of macros SAVE and RESTOR 

for saving and restoring active registers at the beginning and 

end of subroutines. These macros should take a variable number 

of arguments so that, for example, one can write 

SAVE A,SUBRS 
RESTOR A,B,X,SUBRS 

to generate the code 



STA 


SUBRSA 


LDA 


SUBRSA 


LDB 


SUBRSB 


LDX 


SUBRSX 



To this end we first define a macro MOVE which is called 

by the same arguments delivered to SAVE and RESTOR, but with 

the string *ST' or 'LD' appended. 

MOVE MACRO D 
X MRG 

RPT (Y=2,X-1) 

d(i)d(y) d(x)d(y) 

ENDR 
ENDM 

Now SAVE and RESTOR can be defined as 

SAVE MACRO D 

MOVE ST,D(,) 
ENI3M 
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RESTOR MACRO B 

MOVE U),D(J 
ENBM 

2. Many programmers use flags, memory cells that are 
used as binary indicators. The instruction SKM (skip if memory 
negative) makes it easy to test these flags if the convention is 
used *hat a flag is set (true) if it contains -1 and reset (false) 
if it contains 0. We want to define two macros, SET and RESET 
to manipulate these flags; furthermore, it is desirable to 
deliver at call time the name of an active register which will 
be used for the action. Calls of the macros will look like 

SET A,FLG1,FLG2,FLG3 
RESET X,FLG37,FLG12 

As in the previous example we make use of an intermediate 
macro, STORE, which takes the same arguments as SET and RESET. 



STORE 


MACRO 


D 


X 


NARG 






RPT 


(Y=2,X) 




ST.&D(1) 


d(y) 




ENDR 






BmM 




,nd RESET 


are defined 


as 


SET 


MACRO 


D 




ld.&d(i) 


=-1 




STORE 


D(,) 




EWDM 




RESET 


MACRO 


D 




cl.&d(i) 






STORE 


D(,) 




Ewm 





3. The following macro, MOVE, takes any nimiber of pairs 
of arguments; the first argument of each pair is moved to the 
second, but an argument may itself be a pair of arguments, which 
may themselves be pairs of arguments, etc. MOVE extracts pairs of 
argument structures and transmits them to a second macro MOVEl. 



MOVE 


MACRO 


D 


X 


NARG 






RPT 


(Y=1,2,X) 




MOVEl 


D(Y),D(Y+1) 




ENDR 






ENDM 
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The main work is done in MOVEl v^hich calls itself recursively 
\intll it comes up vith a single pair of arguments. 



MOVEl 


MACRO 


D,G,2 


G(l) 


NABG 




G(2) 


EQU 


- 




IF 


G(l)==2 




LEA 


D(l) 




SIA 


D(2) 




ELSE 






RPT 


g(i)/2,{g(2)k;(2)+i) 




MOVEl 


D(G(2)),D(G(2Xl)/2) 




ENDR 






ENDF 






Emm 





When MOVE is called by 

MOVE 

the code generated is 

LDA 
STA 

When called by 

MOVE 

the code generated is 

LDA 
STA 
LDA 

STA 

When called by 

MOVE 

the code generated is 

LDA 
STA 
LDA 
STA 



A,B 



A 
B 



A,B,C,D 



A 
B 
C 
D 



{A,B),(C,D) 



A 
C 
B 
D 
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And when called by 

MOVE ((A,B),(C,D)),((E,F),(G,H)) 
the code generated is 



TM 


A 


STA 


E 


T.M 


B 


STA 


F 


LDA 


C 


S-EA 


G 


LM 


D 


STA 


H 



It is instructive to trace the last example by hand to see how 
the recursive calls of MOVEl work. This is an exercise left 
to the reader. 
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6.0 Operating NARP 



6.1 Starting an assembly 

Assuming that the user has entered the time- sharing system, 
NARP is called 'by hitting the ESCAPE button until the EXEC ansvjers 
(by typing '-',) and then typing *NARP* followed by a carriage re- 
turn. Control is then turned over to NARP and a source file must 
be specified; other information may also be supplied, if desired. 
The general format is: 

default convention 



-NARP. 






SOURCE FILE: 


file name 


none 


OBJECT FILE: 


file name 


none 


TEXT FILE: 


file name 


TELETYPE 



All three files do not have to be specified. 

The various options are discussed in more detail below: 

SOURCE* FILE: As soon as NARP is started this line is typed and 

the user must specify a file containing the programs 
to be assembled. When he terminates the name with a 
carriage return, NARP responds with 'OBJECT FILE;' 
on the next line. 

When the name is terminated with a line feed, no fur- 
ther requests are made. The assembly begins immediately 
and produces no object file or Teletype listing except 
for error messages. This feature is primarily used to 
FREEZE symbols and macros into the symbol table. 

OBJECT FILE: The file name given specifies where the binary output 

from the program should go. If the file name is termi- 
nated by a line feed, then NARP waits for a text file 
to be specified. 

TEXT FILE: The file name given specifies where the listing of the 
source program and of the error messages should go. 
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6.2 Multiple program assembly 

The source file may contain more than one program, each termi* 
nated by an END directive. Each program is assembled separately 
with each binary being appended to the object files • Multiple pro- 
gram object files can be loaded in DDT with no addit;ipn and in FOS 
with the addition of a FIILIB directive. 
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6.3 Assembly of multiple files 

After completing a NARP assembly of one file it is possible to 
run a second NARP assembly which uses definitions made in the first. 
All those definitions preceding the FREEZE directive will be retained^ 
This process may be repeated. Using this feature, it is possible to 
break up sjnmbolic programs which are too large for QED to handle into 
manageable segments. To assemble a second or subsequent file, use 
the CONTINUE command of the EXECutive in place of the NARP command. 
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Appendix A: List of all pre-defined opcodes and pre-defined symbols 

NARP in its original form contained no symbol definitions except 
that for "OPD" . An initialization run was performed using the defini- 
tions given below. The NARP subsystem as available to the DIAL -DATA 
user is an initialized version. That is, the opcodes and symbols 
shown below are already defined, and the user does not make an ini- 
tialization run. 

The following table is a listing of an initialization program 
used to initialize the opcode table and symbol table of NARP. It 
will be noted that in some cases the OPD directive has four operands 
instead of the usual three; the fourth operand specifies the type 
(directive, macro, or instruction) of the opcode being defined. It 
is only possible to use four operands for OPD when NARP is being 
initialized, and once the initialization program has been assembled, 
OPD will only accept three operands. 
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(JAX 


OPl) 


AAA 


Oi^l3 


CnX 


OPD 


cx:-3 


OPD 


XXfJ 


OPD 


ST .•: 


OPO 


LDE 


OPD 


XrCh: 


OPD 


C.\'A 


OPD 


AXC 


OPD 


'B:k\) 


OPD 


3,VA 


Opd 


'SH'ri 


OPD 


BRr< 


OPD 


BR I 


OPD 


SKS 


OPD 


SKE 


OPD 


SKG 


OPD 


SKnJ 


OPD 


SKKj 


OPD 


SKN 


OPD 


SKA 


OPD 


SK3 


OPD 


SKD 


OPD 


KSH 


OPD 


RCY 


OPD 


LKSH 


OPD 


LSH 


OPD 


LCY 


OPD 


NOD 


OPD 


HLT 


OPD 


ZHO 


01-»D 


NOH 


OPD 


KXU 


OPD 


BPTl 


OPD 


BPT2 


OPD 


BPT3 


OPD 


3PT4 


OPD 


ROV 


OPD 


RH!0 


OPD 


OVT 


OPD 


OTO 


Ot^D 


Kli^ 


OPD 


D I ;< 


OPD 


Ai;;: 


OPD 


I r/r 


OPD 


IDT 


Oi'D 



0^60 

('5^1 60 
0/<60 
460 
460 
460 



400B, 1 
600B, 1 
00a0B> 1 
0040B, 1 
00 60B* 1 
(M226, 1 
0140B, 1 
0160B, 1 
1000B, 1 
40 1 B , 1 



001000008,2 
041O0000B,2 
04300000B>2 

5100000 8,2 

01 100000B,2 



5000 
7 300 
6000 
7000 
5300 
7200 
5200 
7400 



000B,2 
0000,2 
000B,2 
000B,2 
000B,2 
000B,2 
000 B, 2 
000 B, 2 
000B,2 



6 600000 B, 2, 1. 
6620000B,2, 1 
66240008,2, I 
67000008,2, 1 
6720,0008,2, 1 
67100008,2, 1 

00000000 8,0 
000000 8,0 
20000008,0 
023000008,2 

4020 400 8, 1 
40202008,1 
40201008,1 
04020040B, 1 

0220000 IB, 1 
022000108, i 
02200 10 IB, 1 
2200 1 008, 1 

002200028, 1 
0022000 48, 1 
00 2200208, 1 
40200028, 1 
040200048, 1 



COPY A INTO X 
EXCHANGFC X AND A 
COPY B INTO X 
COPY X INTO B 
EXCHANGE X AND B 
STOixE EXPONENT 
LOAD EXPONENT 
EXCHANGE EXPONENTS 
COPY NEGATIVE OF A 
COPY A TO X, CLEAR 



INTO 
A 



REDUCE M, 
SKIP IF A 



BrJANCH UNCONDITIONALLY 

INCREMENT INDEX AND BRANCH 

MARK PLACE AND BRANCH 

RETURN BRANCH 

BRANCH AND RETURN FROM INTERRUPT 

SKIP IF SIGNAL NOT SET 

SKIP IF A EQUALS M 

SKIP IF A GREATER THAN M 

SKIP IF NEGATIVE 
EQUALS M ON B MASK 

SKIP IF M NEGATIVE 

SKIP IF M AND A DO NOT COMPARE ONES 

SKIP IF M AND B DO NOT COMPARE ONES 

DIFFERENCE EXPONENTS AND SKIP 

RIGHT SHIFT AB 
RIGHT CYCLE AB 
LOGICAL RIGHT SHIFT AB 
LEFT SHIFT AB 
LEFT CYCLE AB 
NORMALIZE AND DECREMENT X 
) 

HALT 

7JZH0 

NO OPERATION 

EXECUTE 

BREAKPOINT TEST 1 
BREAKPOINT TEST .2 
BREAKPOINT TEST 3 
BREAKPOINT TEST 4 

RESET OVERFLOW 

RECORD EXPONENT OVERFLOW 

OVERFLOW TEST AND RESET 

ovr::RFLOw test only 

ENABLE INTERRUPTS 
DISABLE INTERRUPTS 
AK^M/DISARM INTERRUPTS 
INTERRUPT ENABLED TEST 
INTERRUPT DISABLED TEST 
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ALCVi 


■ DPI) 


nisi-; 


OPD 


A:iGl-i 


OPi) 


TOi^l'; 


OPD 


CAT'v 


OPD 


CiCTl-i 


OPD 


CZTW 


OPD 


ClV'/i 


OPD 


f^Ol.) 


OPD 


(•J I '.-J 


OPD 


VJ I M 


OPD 


i^ I .\' 


OPD 


POT 


OPD 


KOiA 


Oi^D 


uETW 


OPD 


BHTW 


OPD 


TSi\' 


OPD 


CKi\' 


OPD 


CKF 


OPD 


LHAl 


OPD 


U<i<2 


OPD 


Li^j^3 


OPD 


BIO 


OPD 


HKS 


OPD 


CIO 


OPD 


CIT 


OPD 


CT/^L 


OPD 


DBI 


OPD 


DBO 


OPD 


DI'JI 


OPD 


DUO 


OPD 


IlXS 


OPD 


EXSYM 


OPD 


FAD 


OPD 


FDV 


OPD 


FFAD 


OPD 


FFADD 


OPD 


FF 1)1 


OPD 


FFOID 


OPD 


FFD'J 


OPD 


FFOK'D 


OPD 


FFiAP 


OPD 


FFMPD 


OPD 


FFS16 


OPD 


FFSBD 


OPD 


FF SI 


OPD 


FFSID 


OPD 


f:ap 


OPD 


FSB 


OPD 



00 2 '3^0000, 1 
00200000H> 1 
0O212000B, 1 
002 141=) 008, 1 

40 1/J000B, 1 
401 1000B, 1 
4012000B, 1 
40100008, 1 



600 
1 200 
3200 
3300 
1 300 
00200 
4020 
4021 



0008,2 
000 8,2 
0008,2 
0008,2 
0008,2 
0008,2 
108,1 
0008, 1 



002220008, 1 
00 2201008, 1 
002202008, 1 
00220 400 8, 1 
002210008, 1 
002214008, 1 

5 7 6000008,2 
5 73000008,2 
561000008,2 
534000008,2 
5 7200000 8,2 
542000008,2 
543000008,2 
544000008,2 
54 5000008,2 
552000008,2 
515000008,2 
556000008,2 
5 53000008,2 
526000008,2 
520000008,2 
531000008,2 
514000008,2 
530000008,2 
52200000 8,2 
527000008,2 
521000008,2 
53200000 8,2 
523000008,2 
533000008,2 
513000008,2 
554000008,2 
555000008,2 



ALF.KT CHANNEL W 

DISCONNECT CHANNEL W 

ALE/^f TO STOKE ADDKESS IN CHANNEL 

TERMINATE OUTPUT ON CHANNEL W 



W 



CHANNEL 
CHANNEL 
CHANNEL 
CHANNEL 

b:nekgize 

M INTO W 
W 8UFFEK 
PAKALLEL 
PARALLEL 
ENERGIZE 
W BUFFER 
W BUFFER 



ACTIVE TEST 
W ERROR TEST 
W COUNT TEST 
W INTER-RECORD 



TEST 



OUTPUT D 
BUFFER WHEN 
INTO M WHEN 
INPUT 
OUTPUT 
OUTPUT M 
ERROR TEST 
READY TEST 



EMPTY 
FULL 



NORMAL TO MONITOR MODE 

CLOCK ON 

CLOCK OFF 

LOAD RELABELLING 

LOAD RELABELLING 

LOAD RELABELLING 



REGISTER 1 
REGISTER 2 
REGISTER 3 



BLOCK I/O 

BRANCH TO SYSTEM 

CHARACTER I/O 

CHARACTER INPUT AND TEST 

CONTROL 

DRUM BLOCK INPUT 

DRUM BLOCK OUTPUT 

DRUM WORD INPUT 

DRUM WORD OUTPUT 

EXECUTE INSTRUCTION IN SYSTEM MODE 

EXS RELOCATED FROM SYMS IN MONITOR 

FLOATING ADD 

FLOATING DIVIDE 

FLOATING ADD WITH FA 

FLOATING ADD,X DOUBLED 

FLOATING DIVIDE INVERTED WITH FA 

FLOATING DIVIDE INVERTED, X DOUBLED 

FLOATING DIVIDE WITH FA ' 

FLOATING' DIVIDE, X DOUBLED 

FLOATING MULTIPLY WITH FA 

FLOATING MULTIPLY, X DOUBLED 

FLOATING SUBTRACT WITH FA 

FLOATING SUBTRACT, X DOUBLED 

FLOATING SUBTRACT INVERTED WITH FA 

FLOATING SUBTRACT INVERTED, X DOUBLED 

FLOATING MULTIPLY 

FLOATING SUBTRACT- 
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GCD 


OPD 


531(')i)^y)i)('lB,2 


GCI 


OPD 


5650000'rB>2 


ISC 


•OPD 


5 4000000 Bj» 2 


I Si- 


OPD 


5 S0 00 000 By 2 


LAS 


OPD 


54600000B>2 


LD? 


OPD 


56600000B>2 


LDFM 


OPD 


524000O0B>2 


LDFMD 


OPD 


'51600000B^2 


OST 


OPD 


55100000B,2 


SAS 


OPD 


V 5/j700000B>2 


SB;^;f^ 


OPD 


57000000 3,2 


SSRR 


OPD 


5M0000B>2 


SIC 


OPD 


5/U00000B,2 


sksp: 


OJ^D 


563000 00B> 2 


SKSG 


OPD 


56200000 8,2 


STFM 


OPD 


525000008, 2 


STFMD 


OPD 


517000008,2 


ST I 


OPD 


536000008,2 


STP 


OPD 


567000008,2 


TCI 


OPD 


574000008,2 


TCO 


OPD 


57 500000 8,2 


WCD 


OPD 


53 500000 8,2 


VICH. 


OPD 


564000008,2 


WCI 


OPD 


557000008,2 


WIO 


OFD 


560000008,2 



GET CHAKACTEk AND DKC/'JIlMKiNJI 

GET GHARACTEP AND INCKEMENT 

INTERNAL TO STRING C0NV<FL0ATING OUTPUT) 

INPUT FROM SPECIFIED TELETYPE 

LOAD FROM SECONDARY MEMORY 

LOAD POINTER <AB) 

LOAD FLOATING ACCUMULATOR 

LOAD FLOATING ACCUMULATOR, X DOUBLED 

OUTPUT TO SPECIFIED TELETYPE 

STORE IN SECONDARY MEMORY 

SYSTEM 8RM 

SYSTEM BRH . 

STRING TO INTERNAL CONV (FLOATING INPUT) 

SKIP IF STRINGS EQUAL 

SKIP IF STRING GREATER 

STORE FLOATING ACCUMULATOR 

STORE FLOATING ACCUMULATOR, X DOUBLED 

SIMULATE TELETYPE INPUT 

STORE POINTER (AB) 

TELETYPE CHARACTER INPUT 

TELETYPE CHARACTER OUTPUT 

WRITE CHARACTER AND DECREMENT 

WRITE CHARACTER 

WRITE CHARACTER AND INCREMENT 

WORD I/O 



* DIRECTIVE DEFINITIONS 



ASC 


OPD 


0,2,0,1 


BES 


OPD 


1,2,0, 1 


BSS 


OPD 


2,2,0,1 


COPY 


OPD 


3,2,0,1 


CRPT 


OPD 


4,2,0, 1 


DATA 


OPD 


5,2,0, 1 


F 1 1 L I B 


OPD 


6, 1,0, 1 


DEC 


OPD 


7, 1,0, 1 


DELSYM 


OPD 


8, 1,0, 1 


ELSE 


OPD 


9, 1,0,1 


ELSE 


OPD 


10,2,0,1 


END 


Ol^D 


11,1,0,1 


ENOF 


OPD 


12,1,0,1 


EN .DM 


OPD 


13,1,0,1 


ENDR 


OPD 


14,1,0, 1 


EG)U 


OPD 


1 5,2,0, 1 


EXT 


OPD 


16,0,0, 1 


FREEZE 


Oi^D 


17, 1,0, 1 


FRGT 


OPD 


18,2,0, 1 


I DENT 


OPD 


19,1,0,1 


IF 


OPD 


20,2,0, 1 


LIST 


OPD 


21,0,0,1 


MACRO 


OPD 


22,0,0,1 


NARG 


OPD 


23,1,0, 1 



ASCII STRING 

BLOCK END SYMBOL 

BLOCK START SYMBOL 

REGISTER CHANGE 

CONDITIONAL REPEAT 

DATA WORD 

FORTRAN II LIBRARY 

SET NUMBER RADIX TO 10 

DELETE SYMBOL 

ELSE 

ELSE IF 

EN!) OF Pi^OGRAM 

END IF 

END MACRO 

END REPEAT 

EQUATE 

EXTERNAL 

FREEZE TABLES 

FORGET SYMBOL 

IDENTIFICATION SYMBOL 

IF 

TURN ON LISTING 

MACRO DEFINITION 

NUMBER OF ARGUMENTS 
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NCHK 


OPD 


24>0*0>1 


LOCCNT 


OPD 


25*2,0*1 


NOLI ST 


OPD 


26*0*0*1 


OCT 


OPD 


27*1*0*1 


POPD 


OPD 


2^*2*0*1 


RELOHG 


OPD 


29*2*0*1 


RETKEL 


OPD 


30*1*0*1 


RPT 


OPD 


31*2*0*1 


TEXT 


OPD 


32*2*0*1 


LMACRO 


OPD 


33*0*0*1 


GLOBAL 


OPD 


34*1*0* 1 


REM 


OPD 


35*2*0*1 


LOCAL 


OPD 


36*1*0*1 


Fi^GTOP 


OPD 


37*2*0* 1 


CSECT , 


OPD 


38*2*0*1 


NBSS 


OPD 


39*2*0*1 


:ZERO: 


EQU 


* 


:LC: 


ECOU 


:ZERO: 




FRGT 


:ZERO:*:LC: 




FREEZE 






END 





NUMBER OF CHARACTERS 

LOCATION COUNTER 

TURN OFF LISTING 

SET NUMBER RADIX TO 8 

POP DEFINITION 

RELATIVE ORIGIN 

RETRIEVE ORIGIN 

REPEAT 

STRING (FOUR CHARACTERS PER WORD) 

ALTERNATIVE MACRO DEF'N 

SET GLOBAL MODE 

PRINT REMARK ON TEXT FILE 

SET LOCAL MODE 

FORGET SELECTED OPCODES 

CONTROL SECTION 

NONCOMMUNICATIVE BSS 



LAST LINE OF NARP INITIALIZATION PROGR 



